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PREFACE. 


Taligent Tools for AIX is a reference guide to the tools that Taligent engineers use 
in everyday development work on the AIX® platform. Most of these tools were 
developed specifically for building the Taligent Application Environment® and 
the Taligent Operating System. 
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A QUICK START 


This summary, for internal Taligent developers only, is a quick overview to the 
topics of this book. It includes information on: 

# Setting up and using your AIX system, page xi 

« The SNiFF+ programming environment, page xvi 

# System tests, page xix 

# Defect and change control procedures for Taligent Operating System, 

page xxii 

« Problem reporting page xx 
This summary is intended to quickly get you using the tools necessary to build 
Taligent systems and applications. This is not a substitute for the rest of this book, 
or for other more detailed company guides. To learn about the SNiFF+ 
programming environment, see the “Getting started” chapter in the SNFF+ 
Reference Guide (Part II of Taligent Tools for AIX). Also, The Methodologies and 
Processes Binder (The MAP) explains the Taligent software development: 
methodologies and processes. 


GETTING STARTED 


The instructions in this section will help you quickly set up your AIX 
environment so that you can start building your code. However, the instructions 
are terse with little or no explanation. For more detailed information on setting 
up and using your AIX environment, see “Working in the AIX environment” on 
page 3, which covers these steps in greater detail. 
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Setting up for the | Ask Technical Support to set up your AIX workstation with the Taligent 
first time standard setup and establish the appropriate server connections. 


Install the default startup files. This will overwrite the .cshrc, .profile, 
-mwmrc, .Xdefaults, .login, .xinitrc, and .emacs files on your system. 


® For layer work: 


cd /usr/taligent/defaults 
InstallDefaults 


® For native work: 
/usr/taligent/defaults/NativeInit ~/Work 


Log out completely and log in again to ensure proper execution of the new 
scripts. To log out: 


® Choose End Session from the root menu by holding down the right 
mouse button on the desktop background. | 


@® Choose OK. 
For layer work, create a working directory. The working directory will become 


what is known as your $TaligentRoot. (Although you don’t have to call your 
working directory Work, this is the Taligent standard name.) 


cd $HOME 
mkdir Work 


Initialize the environment variables. The option -1 indicates that you always 
want the latest build. The -c option creates all of the $TaligentRoot 
subdirectory trees on your local machine. 


© For layer work, 
SetRoot -1 -c ~/Work 
@® For native work: 


NativeRoot -1 -c ~/Work 
“NOTE You need to run SetRoot or NativeRoot each time you log in toa 
terminal session that uses the Taligent build environment. If you get an error 
message like “#### Command: Environment variable $TaligentRoot must be set!”, 
it is because you didn’t run SetRoot or NativeRoot in the session. 
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Installing builds To install a build for the first time: 
Verify that your machine has 400 Mbyte of free disk space. 


df 


Install the latest build: 


@ For layer work, 


cd ~/Work 
InterimInstal ] 
SetRoot ~/Work 


@® For native work: 


cd ~/Work 
Nativelnstall 
NativeRoot ~/Work 


Updating builds To update to a later build 
For layer work, (the -b first removes the existing build): 


cd ~/Work 

SetRoot ~/Work 
InterimInstall -b 
SetRoot ~/Work 


For native work: 


cd ~/Work 
NativeRoot ~/Work 
NativelInstall -b 
NativeRoot ~/Work 


PEPER MELEE EEN ALAM MMM MLM tl eicceecltanbectthidicccretatteticen ind cock 


Running layer To run a program on the layer, first start the layer, and then run your program. 
peu Start the layer: 


cd $TaligentSharedLibs 
StartPink 


Run the Macrame program: 
Macrame & 
Quit the Layer: 


cd $TaligentSharedLibs 
StopPink 
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Locating sample 
applications 


To run a Taligent Geet System program: 


Ei Transfer your progres (/home/mpogue/MyTest) as aay to an Intel machine 
(chrome): 


cd $TaligentSharedLibs 
ftp chrome 
type binary 
cd sone mpesyennyess 
put Macrame 


Start your program: 


rlogin chrome 
cd /home/mpogue/test 
rp Macrame & 


Stop your program: 
® Run jobs to list running programs. 


jobs 
[1] + Running rp 


@ Run kill to stop the program. 
kill -9 %1 
[1] Terminated rp 
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The $TaligentSharedLibs directory contains libraries and sample applications. If 
you aren’t already in the working directory, move there. 


cd $TaligentSharedLibs 


Here are three sample layer applications: 


# To start the Mars application: 
Mars documentName & 
# To start the RunDocument Application: 
RunDocument -c -o TTextStationery EditableTextLib& 


# To start the Workspace Application (which brings up the Taligent Workspace 
Environment): 


CreateWorkspace 
LaunchWorkSpace 


TALIGENT INTERNAL TOOLS TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


PRELIMINARY 


repository 


PRELIMINARY 


nate E AECL OEE LEE CELL EEEL OEE CER P TELCO TE LIES OP ELECTED COPE LEO LP ELEC O LEER TOE LOOT OLE LED 


A QUICK START 
GETTING STARTED 


The source code repository is located in $TaligentSCMRoot. The directories on 


your local machine (created with SCMCreateDirectories) are parallel to the 


repository directories. 


Taligent has a set of wrappers and extensions for accessing files in the repository. 
For example, when files are checked in or out, they are each associated with a 
specific build version number such as D31.1. Here is summary of the key 
commands and useful options to use when checking source in and out. 


Checkout -a -r 


Checkout -a -r -v D31.1 


Checkout foo.C 
Checkout -m foo.C 


NameVersions -f f00.C 
Checkin -a -r 


Checkin -i foo0.C 


Checkin -a -r -n D31.1 
CompareVersions D30.1 D31.1 


CompareVersions -latest 
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Recursively checks out the latest build. 


Checks out all of the files in the directory that 
are in the D31.1 release. 


Checks out the latest foo.C file. | 
Checks out the latest foo.Cc file for modification. 


Display a list of all of the versions available for 
foo.C. 


Recursively checks in all of the files that are 
checked out. 


Checks in foo.C for the first time. 


Recursively check in all of the files that are 
checked out and set their build version to D31.1. 


Compares what files have changed between 
build D30.1 and D31.1. 


Shows what has changed in the current 
workspace directory compared with the latest in 
the repository. 
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S iiias SOURCE CODE EDITING AND 
BROWSING WITH SNIFF+ 


LEELLE PELE LLL ELL ELLE LOLOL CET Ce 


LPL MLL ELLA LOL ILI PEP EL OIL LED EMP OLDE OES 


Crating a rorilact 


SNiFF+ provides a C/C++ development environment for browsing, cross- 
referencing, design visualization, documentation, editing, and debugging. 
SNiFF+ makes it possible to rapidly edit and browse large software systems in 
both a textual and graphical manner. 


For more detailed information about SNiFF+, see the diane started” chapter 
in the SMFF+ Reference Guide (Part II of Taligent Tools for AIX). 


To use SNiFF+, you need to set three environment variables: 
« In C Shell: 


setenv SNIFF_DIR /usr/talilocal/packages/SNIFF 
setenv LM_LICENSE_FILE $SNIFF-DIR/license.dat 


In your .cshrc file change the PATH variable to include: 
$SNIFF_DIR/bin 
# In Korn Shell or Bourne Shell: 


SNIFF_DIR=/usr/talilocal/packages/SNIFF; export SNIFF_DIR 
LM_LICENSE_FILE=$SNIFF_DIR/license.dat; export LM_LICENSE_FILE 


In your .profile file change the PATH variable to include: 


$SNIFF_DIR/bin 


neat. 


To work in the SNiFF+ programming environment, you must have a SNiFF+ 
project. This can be done from inside SNiFF+ by following the instructions in 


- “Creating a new project” in the SNiFF+ Reference Guide (Part III of Taligent Tools for 


AIX). Or, more easily, from outside of SNiFF+ with genproj, a command that 
creates a project consisting of all of the files in the specified directory, as well as 
creating subprojects in all of the corresponding subdirectories. SourceDirectory 
is your working directory, and ProjectName is the name you want to call the 
project. The -e indicates that subprojects should not be created in empty 
subdirectories. 


genproj SourceDirectory -p ProjectName -e 


"£ NOTE Tosee all Taligent header files in your project, create a subproject to 
your project, and include in that subproject the header files in $TaligentIncludes 
($TaligentRoot/TaligentIncludes/Public). 
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Editing in SNiFF+ SNiFF+ provides two choices for editing source code: 
« SNiFF+'s own integrated editor (the default). 
« An interface to standard emacs. Refer to “Emacs integration” in the SNiFF+ 


Reference Guide (Part II of Taligent Tools for AIX) to understand how to 
establish an interface between emacs and SNiFF+. 


To edit source files: 


Check out the layer sources you want to work on: 


SetRoot ~/Work 
SCMCreateDirectories 

cd theDirectoryYouWantTowWorkIn 
Checkout -a -r 


Start SNiFF+ with or without a project name. If you omit the project name, 
SNiFF+ loads an empty project. Starting SNiFF+ with a project name loads all 
of the source files, symbols and classes associated with that project for 
browsing and editing in SNiFF+'s editor window: 


sniff MyProjectName & 


Compiling and linking §=The SNiFF+ programming environment currently works well for editing, 
browsing and debugging code. However, until SNiFF+ is integrated with the 
Taligent build tools, you need to compile and link projects in a UNIX shell. This 
shell can be either the Shell Window in SNiFF+ or a regular AIX shell window. 


To compile and link: 


SetRoot ~/Work 


If the layer is running, stop it before executing Makeit: 


cd $TaligentSharedLibs 
StopPink 


Run Makeit to build your project: 


cd theDirectoryYouWantToWorkIn 
Makeit 


Makeit reads the <project>.PinkMake file and creates a makefile to compile 
and link the project. To understand the syntax of the PinkMake files, see 
“Makefiles” on page 43. You don’t need to change the *. PinkMake file unless 
you add a new module to your project. 


CAUTION The current build tools do not test to see if your component, 
application, or library has the same name as one used by the system. The build 
process will automatically overwrite the Taligent file with yours if you have a 
duplicate name. 
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application 


The linker, during Makeit execution, installs each compiled executable program 
in $TaligentSharedLibs. To run the application from an AIX shell window: 


Restart the layer that was stopped for Makeit: 


cd $TaligentSharedLibs 
StartPink 


Run your application: 


YourApplicationName & 


SNiFF+, through its communication with either the gdb or dbx debugger, can be 
used to debug applications. Taligent 's specialized version of gdb is the default 
SNiFF+ debugger. The gdb executable is located in /usr/1ocal/bin/gdb. 


Before running the debugger in SNiFF+, set up the Project Editor Preferences: 


Double click the project name in the bottom area of the SNiFF+ window. A 
Preferences dialog will appear. 


Verify or setup the target (your application’s name), the source path (the 
path to your source code), and the Make command (it should be Makeit). 


To start the debugger from within SNiFF+, choose Debug Target target from the 
Exec menu of the Editor. This launches the debugger in a separate window from 
which you can set breakpoints, step through code, and print variable values. 


If you don’t want to debug within the SNiFF+ environment, use xcdb. This 
debugger brings up its own windowing environment in which to debug. Launch 
xcdb by using the Taligent script xdb along with the SourcePath option 
containing the path to your source. 


xdb [-s SourcePath ... ] yourApplicationName 
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Taligent uses three kinds of system tests: Basic Acceptance Tests (BATS), 


Subsystem Tests (SSTs) and System Test Applications. 


BATs To see what BATs are available and how to execute them: 


cd $TaligentSharedLibs 

RunBATS -h gives help on running BATs 
RunBATS -1 lists the available BATs 
RunBATS <BATname>runs the specified BAT 


The BAT source code is located in the $TaligentRoot/Tal i 
directory structure. 


gent/Testbed/BATS 


SSTs Numerous tests exist for the various subsystems of the layer. To install the 


prebuilt SSTs, use InterimInstal1 with the -T option. 


InterimInstall -T 


The SST test programs are in <SSTtestname>/scripts and <SSTtestname>/bin 
subdirectories within $TaligentSharedLibs/Test/SST. There is a wide variety of 
SSTs available that you should try. For example, an audio video test which 


executes a movie clip: 


cd $TaligentSharedLibs/Test/SST/AVTests/scripts 
AVTests.sh 


The SST source code is located in the $TaligentRoot/Taligent/Testbed/ 


SubSystemTests directory structure. 


For a complete explanation of all of the SSTs locations, execution instructions 


and result interpretations, reference the Test Roadmap in 


Central Services:Taligent Library:Test Doc Library:Test Doc:Tests. 


ystem test The System Tests Applications should now be available, but information was not 


applications available when this book went to print. Please check with Product Test for 
| information. 
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When you file a ProTeam problem report, the two key fields that indicate a 
problem report’s state are Status and How Resolved. Here are the possible values 
for those fields and what they mean in a problem report’s life cycle: 
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When tested or 
examined, and the 
problem still exists 
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When tested or 
examined, and the 
problem still exists 
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- Here are the standard definitions used by Taligent Operating System for 
submitting ProTeam defect reports. 


Priority field 


Status field 


How Resolvedfield =F 


This is the default status for all new problem reports (either code or 
documentation). Open means action needs to be taken. 


Code has been changed to repair the problem or feature. An ICBM notice has 
been submitted. The code has been checked in, and name revisioned. The How 
Resolved field should be set to "Fixed" or ‘Obsolete/Will Not Test’. Remember, 
you must also fill in your ICBM number. 


There has been no change to code or documentation. Closedis used in 
conjunction with several of the "How Resolved" field choices, for example, 
Cannot Reproduce, Duplicate, pusnlEle User Error, and As Designed. 


The problem report has been verified | in a master build and the "How /Resolved" 
answer confirmed (such as “Yes it’s fixed, yes there was User Error”). Fill in 
the Verified By and Verified Build fields. 


This problem report will not be addressed in the current release. The Bug 
Priority Meeting (BPM) makes this decision. If a defect is deferred, its status 
will change to Open once the current release ships. 


~ Code changes have been completed and the ICBM form submitted. = 


Documentation corrections have been completed. Status also becomes Fixed 


There’s another report, or several reports detailing this same problem. You 
should fill in the duplicate problem report number or numbers in the Duplicate 
# field. Stalls becomes ee 


The code or documentation is now w obsolete. No change tos source e code o or 


documentation will occur. Status becomes Closed 


The code or documentation is now obsolete. Code or documentation might 
have changed, but became obsolete before testing was performed. Status 
pecuTEs peuned 
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User Error 


‘WillNotFix = 


Deferred 


Serious 
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Moderate 


Minor 


‘Functional Areas and _ ~ Note that functional a areas s and components do not always map directly to products. Some components 


The reporter of the defect has misinterpreted how the software functions. 
Status becomes Closed. 


Use this field in conjunction with the Status field. 


Additional Considerations Here: Does this user error indicate a problem in the 


documentation? Should TechComm be notified? If the answer is “yes”, you 
have two choices: 


e Write a new problem report against the documentation 


e Change this report’s Funct Area, Component, and Report Type to reflect a 
Documentation Error and enenge the status to meet 


The problem will not be fixed for reasons noted in the descriptior an 1. Again, or 


check the documentation for accuracy and clarity. Status becomes Closed. 


The ICBM or Release Team has decided this problem report should not be 
addressed ie slats pecomes palatial 


The problem results j in ‘data loss or ‘the corruption of data. There i is n no 10 work- 7 


around to the prepiem and it is auecty Impeding a comple on of MIN 


The problem severely limits the use of the system. or - diminishes the 
functionality of the system. A work-around is available for problem allowing 
work to continue. 


The problem limits the use of the system, but the majority of the necessary 
work can be nee ‘ OIE ronee is available: 


The problem is annoying or - unaesthetic, ‘but is ‘not 2 a | compromising problem. 


Components fields appear in several products, while others appear only in one particular Bee Don’t make any 
assumptions ane, products; when Sone defects. 


ICBM Scheduled Build field Along with future builds, this field also lists future products so that you can indicate when you are 


_dererring or cee na a HHESONSE to the problem foyer 


“Product field ~ Indicates the product on n which you found the bug. ‘Any subsystem that is is ; not targeted for z a 1 release, i is _ 


organized under the Internal product. 
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{4 NOTE If you have a bug that occurs on multiple source streams (layer and 
native, for example), submit the defect against the functional area and 
component in the layer responsible for the defect. For example, all Collections 
defects, even those that were found first on the Intel platform, need to go to: 


Product = “Layer SDK1” 
Functional Area = “Collections Text” 
Component = “Collections” 
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If you have a bug that occurs on both native and OODDM builds, but the code is 
not there in the layer build, submit the defect against the native build. If you’re 
not sure who to submit the defect against, ask your manager. There might be 
unusual cases that need to be handled differently. 
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auc DEFECT AND CHANGE CONTROL PROCESS 
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Taligent Operating System uses a simplified version of the defect resolution and 
change process used by Taligent Application Environment. This section summary 
covers the steps to make and submit changes for the native Taligent Operating 
System build. This summary assumes that you are familiar with the basics of 
source control, and with the Taligent DIF development process. 


‘NOTE Follow these steps carefully to ensure that your defect change is 
tracked properly. If you don’t do it correctly, your change will probably get stuck 
somewhere, while the Build Team tries to figure out what you really meant to do. 
This could cause your fixes to be delayed! 


Detect goes to [J Submit a defect report, using ProTeam. This report normally takes less than 
OPEN state. 5 minutes to fill out. 


You need to submit a ProTeam defect for all defects, and problems. Soon the 
ICBM tickets will have ProTeam numbers, and vise-versa. 


Defect goes to ——----------—- Fix the defect. Open ProTeam, and change the state to Fixed. Save it. 


FIXED state. If the resolution of the defect requires a change to the build, then the 


resolver needs to fill out an ICBM ticket. 


© Open the ICBM database, using the ICBM DB Opener. Filling it out gives 

you a ticket number, for example, Native. 1234. ICBM tickets typically 

take about five minutes to fill out. See “Filling out ICBM forms” on 

page xxiv for more information. 
af =NOTE The Build Team does not own any code. Engineers own PinkMake 
files, scripts, source code (*.c, *.h), and documentation (*.d). In some cases, 
there is old code in the build because many of files were simply moved over from 
the 68K build tree. If these files are in your functional area, then you own them. 
This ensures that the right thing is done with the files (deletion, .PinkMake 
modifications, renaming, and so on). 


EI Use NameVersions on all affected files. This is not necessary if the files are 


being deleted. This way, only the .PinkMake will change. You will have to 
submit an ICBM ticket for the .PinkMake change. 
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Zi Copy the new version numbers and filenames into the ICBM ticket. 


Defect goes to ——-------------- 
VERIFIED state. 


Sap 


Sis 


The ICBM ticket is then scheduled for a build. Normally this happens at the 
weekly Intel bringup/ICBM meeting (Thursdays, 1PM), but high priority 
ICBM tickets can be scheduled when needed upon request. Open ProTeam, 
and set the “Scheduled Build” field to the correct value. 


When you verify that the bug has been fixed in an actual build, open 
ProTeam and set the "How resolved", “Verified by:”, “Actual Build”, and 
"Verified Build” fields in the ProTeam bug report (see “Be sure to close the 
window, and log completely off the ICBM database, so others can use it 
efficiently—you must quit FileMaker Pro entirely.” on page xxv). Change the 
state to “VERIFIED”, and save it. 


NOTE The assigned engineer is responsible for keeping the ICBM and 


ProTeam databases synchronized and up-to-date. 


Filling outICBM forms = To get the latest opener, see PacerForum Tech Talk:TalAES Integration: ICBM. 
Also see that forum for instructions on how to be notified about ICBM forms. 


if Open the ICBM database. When it asks for a password, just leave it blank, 
and click OK. 


Create a new Change Notice with Cmd-N. The form will give you a unique 
revision string at the top of the form that looks like this: 
Native. changeNumber 


This is the name you use with NameVersions on your changed files. 


Give the new Change Notice a meaningful title, for example, “PinkKMake 
should not refer to foo.h”. 


Fill out the Submitter field with your name. Use the pop-up menu to ensure 
consistency. Select the proper Functional Area using its pop-up menu. 


For Target Build, select “Native”. 


If architect approval is required, get it. Then, check the Architect Approved 
check box, and select the architect’s name from the pop-up menu. Currently 
your architect in Taligent Operating System is Roger Webster. 


Check the correct Change Classification, Change Type, and Client Impact. If 
these fields are confusing, ask your manager for clarification. 


In the Fixed Bugs field, put the ProTeam defect numbers for all defects 
repaired by this change. There are very few cases where an ICBM ticket will 
not have an associated defect number. If you haven’t ancaey filed a defect for 
this change, do so now. 
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E If your ICBM ticket requires that previously submitted ICBM’s be integrated 
before this one can be integrated, put the dependent ICBM’s number into 
the Dependent ICBM (s) field. 


Eid Check in the files associated with the change. Perform the name-revision 
(with NameVersions) on the affected files, using the string from the form. 


Generate a list of all affected files, and put it into the “Generate ALL file 
paths...” field. Each filename must contain the SCM revision number 
associated with the file. 

Go back to the Change Notice form and click the check box called "Form 


t 


Completed and files name revisioned ‘Native.XXXX’....". 


Be sure to close the window, and log completely off the ICBM database, so others 
can use it efficiently—you must quit FileMaker Pro entirely. 
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CHAPTER 1 


INTRODUCTION 


Taligent Tools for AIX describes the Taligent AIX development tools and how to 
use them. It also includes instructions for setting up your Advanced Interactive 
Executive (AIX) environment. 


This guide assumes that Technical Support has installed the Taligent standard 
setup on your AIX workstation. It also assumes that you are running the C Shell 
(csh) which is the standard shell used for the Taligent build environment. If you 
intend to use a different UNIX Shell, refer to the documentation appropriate for 
that shell. 
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CHAPTER 2 


WORKING IN THE ALX 
ENVIRONMENT 


Before you can build the Taligent Application Environment, the Taligent 
Operating System, or an application for it, you need to set up your AIX 
workstation. To build these applications, you need to know how to check source 
files in and out, how to build programs, and how to start and stop the layer or 
system. 


To ensure that your environment will work with the Taligent AIX tools, you aged 
to create a working environment compatible with the Source Code Management 
(SCM) and Build tools. For information about the SCM or Build environment, 
see the subsequent chapters. 
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SETTING UP FOR TALIGENT APPLICATION ENVIRONMENT 


If you are working on or using the Taligent Application Environment, follow the 
setup instructions in this section. If you are working on or using the Taligent 
Operating System, follow the instructions in “Setting up for Taligent Operating 
System” on page 6. 
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Get the default Use Instal1Defaults to copy the Taligent provided startup scripts (.cshrc, 

startup scripts -login., .profile, .mwmrc, .Xdefaults. and .xinitrc). These scripts were created 
by the Tech Support and Build teams and they set up initial values for various 
important shell variables related to building and running the layer, and then 
merge the old and new files. Once you have run this command, you should never 
need to run it again. 


“@ NOTE InstallDefaults overwrites the startup files already in your home 
directory. If you wish to save the information in your current startup files, rename 
your files before running the install script. 
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Run InstallDefaults. 
/usr/taligent/defaults/InstallDefaults 


Instal1Defaults copies the files in the /usr/taligent/defaults directory 
(folder) to your home directory. 


Completely log out and log in again in order to ensure proper execution of 
the new scripts. To log out: 


© Choose End Session from the root menu by holding down the right 
mouse button on the desktop background. 


@® Choose OK. 
Create y your ir Work Create the working directory where you want to install the Taligent Application 
directory Environment files. This directory name will eventually be the value of your 


$TaligentRoot shell variable. 


Move to your home directory. 


$home is aC Shell (csh) ----—-—- cd_ $home 
variable that contains the : 
value of your home Create the working directory. (You can use any legal AIX filename; however, 
directory this manual assumes that it is called Work.) 
mkdir Work 


Create the root directory for your copy of the source code tree. 


OF ec 


is acsh shortcut that refers 
to your the home directory. 


mkdir ~/Work/Taligent 


CAUTION Do not create symbolic links from one directory to another, or from . 
one file to another, in the repository or in your workspace. Problems can occur 
because the tools see these links as two separate directories. 
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Initialize your 
environment 


brats your copy 
of source tree 


Install the build 


Initialize your environment with SetRoot. SetRoot sets the value of $TaligentRoot 
and several related shell variables. $TaligentRoot is the directory from which all 
of your Taligent Application Environment directories and files descend. 


Run SetRoot and specify your working directory. Optionally, you can include 
-0 to specify Optimize during compilation. 


SetRoot -1 ~/Work 


NOTE You need to run SetRoot each time you login to a terminal session that 
uses the Taligent build environment. If you get an error message like 

“dH## Command: Environment variable $TaligentRoot must be set!”, it is because 
you didn’t run SetRoot in the session. 


Never set $TaligentRoot directly—use SetRoot instead because it also sets other 
important related variables. For more information, see “SetRoot” on page 38. 


To work with source files and use the SCM tools, you must set your source tree to 
mirror the directory structure in the SCM repository. Use SCMCreateDirectories 
to create the directory structure in your environment. 


Move to your Taligent directory. 
cd $TaligentRoot/Taligent 
Run SCMCreateDirectories. It might take a few minutes to complete. 


SCMCreateDirectories 


For more information, see “SCMCreateDirectories” on page 32 and Appendix B, 
“Taligent source code maintenance” on page 171. 


To install the current Taligent Application Environment build, run 
InterimInstall. InterimInstal1 is a temporary script that installs a build into 
your Work directory. 


Move to your Work directory in your working directory. 
cd $TaligentRoot 

Run InterimInstal1. It might take a few minutes to complete. 
InterimInstal] 


For more information, including how to specify particular builds to install, see 
“InterimInstall” on page 64. 
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If you are working on the Taligent Operating System, follow the setup 
instructions in this section. If you are working on the Taligent Application 
Environment, follow the instructions in “Setting up for Taligent Application 
Environment” on page 3. 


Ae 0 aaa Wa 


Prepare your 
environment 


Use NativeInit to set up your entire AIX environment and prepare it for 
building Taligent Operating System code. Once you have run this command, you 
should never need to run it again. NativeInit 


# Sets up the .cshrc, .login, .profile, .mwmrc, .Xdefaults, .xinitrc, and 
.TaligentStartup files. These scripts, created by the Tech Support and Build 
teams, set up initial values for various important shell variables related to 
building and running the layer, and then merge the old and new files. 

# Sets your environment variables correctly. 

# Creates a directory tree (wherever you want it) to hold Taligent Operating 
System source code and binaries. This tree is called your workspace. © 


{@NOTE NativelInit will request to backup your existing startup scripts 
(.cshrc, etc.). The default is to save copies of your files. 


To prepare your environment: 


Run NativeInit and specify the absolute path for your workspace. If the 
workspace directory doesn’t exist, NativeInit creates one for you. 


/usr/taligent/defaults/NativeInit ~/Work 


Log out completely and log in again in order to ensure proper execution of 
the new scripts. To log out: 


® Choose End Session from the root menu by holding down the right 
mouse button on the desktop background. 


@® Choose OK. 
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To install the current Taligent Operating System build into the directory 
structure you have just created, run NativeInstal1. This script installs binaries, 
libraries, and tools into the proper places in your workspace (install source code 
separately with Checkout). 


Move to your Work directory. 


cd $TaligentRoot 


Run Nativelnstal1, it might take a few minutes to complete. For this 
transition, the release name is N10.1. 


NativelInstall -b -r N10.1 


NativeInstall automatically retrieves the tools that the specified build requires, 
and installs them in the correct $TaligentRoot/ToolsDir. Unlike the layer build 
environment, native tools are always synchronized with native source code 
releases to help ensure correct builds. You can override tool installation with the 
NativeInstall -T option. 


CAUTION Do not create symbolic links from one directory to another, or from 
one file to another, in the repository or in your workspace. Problems can occur 
because the tools see these links as two separate directories. 


NOTE Do not use InterimInstal1 (for Taligent Application Environment) 
and NativeInstal1 to install in the same workspace. 


If you want to be able to switch between the two build environments, know that: 


« Nativelnit dzrectoryName performs a NativeRoot directoryName as part of the 
installation procedure. NativeRoot is equivalent to the SetRoot command 
used in the layer environment. 


# You can switch between build environments, as long as you always execute 
NativeRoot directoryName or SetRoot directoryName first. Be careful, because 
these commands change .TaligentStartup in your home directory. Because 
of this, you can’t easily have a simultaneous native and layer build. 
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For details about building projects, see Chapter 4, “The build environment.” 
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CHECKING FILES IN AND OUT 


Change your working 


directory first 
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Examples 


Once you have set up your environment to work with the SCM and Build tools, 
you can check source files in or out of the SCM version control database. To 
check files in or out, use the Checkin and Checkout commands. These and other 
SCM tools are documented in Chapter 3, “Taligent SCM tools.” For information 
about the SCM database, see Appendix B, “Taligent source code maintenance.” 


Before using Checkin or Checkout, you must move to the directory in your 
workspace to which the corresponding files will be checked out. This directory 
corresponds to the directory in the project hierarchy where the source file 
resides. For example, to check out the files from the HeapTool project, change 
your current directory accordingly: | 


cd $TaligentRoot/Taligent/Instrumentation/HeapTool 


Checkout retrieves files from the SCM directory hierarchy and puts them into 
your directory hierarchy—your working directory. For information about 
Checkout, see “Checkout” on page 22. 


Check out read-only copies of the latest versions of the specified files: 
Checkout filel file2 ... 

Check out modifiable (-m) copies of all (-a) the files in the project directory: 
Checkout -m “a 

Check out versions of all files corresponding to the symbolic name D4Release: 


Checkout -v D4Release -a 


Check out all the files in the project directory that have the symbolic name 
d32,1_Final. The -r option tells Checkout to operate recursively in all 
subdirectories in the project and performs the same Checkout in each. This 
example gets the sources for a particular build: | 


Checkout -v d32.1 Final -a -r 
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New files In order for the SCM files to work properly, source files require a comment near 
the beginning of the file that contains either "$Revision:$" or "$Header: $". The 
SCM tools store the file’s version information in this string, and update it every 
time you check the file out. 


Files you check out should already contain one of these two magic strings. You 
need to include one of these strings when checking in a file new to the project. 
When you use Checkin -i to check in a new file, it calls SCMInsertHeader to insert 
the string for you. For more information, see “SCMInsertHeader” on page 36. 


rere re eee eee eee eer eee ee errr eee ee rr eee rece ree eee reer eer ieee eee eT eee rere eee revere ree eee eee ere err eer er eee eee eer eee rere eee ieee ee eee eee reer ee terre eee ree eee ee eee ee 


Checkin Checkin submits your changed files into the SCM repository. For information 
about Checkin, see “Checkin” on page 19. 


Examples Initialize the file. Use this when a file is not already in the project. This command 
checks in the first version of the file. If your working directory has no 
corresponding directory in the project, you get an error: 


Checkin -i filel 


Initialize the file, and create a project directory if one does not already exist that 
corresponds to this working directory. This is useful when first checking a whole 
subtree into the project: 


Checkin -I filel 
Check in all files and immediately check them out for modification: 
Checkin -m -a 


Check in files and designate the newly checked-in versions with the symbolic 
name ap_latest, even if another version of the file is already designated with that 
name (see “NameVersions” on page 28 for information about symbolic names): 


Checkin -N ap_latest filel file2... 
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Making a branch 


Using a branch 


To create a branch, check a version out for modification, then check it in again; 
Checkout does not actually create the branch—Checkin does. The method for 
branching depends on whether or not the version you are branching from is the 
highest version on the trunk or branch. 


To branch from version 1.27 of a file, when version 1.27 is not the last version on 
the trunk, use: 


Checkout -m -v 1.27 file 4¢ Gets version 1.27 for modification. 
Checkin -f file ## Creates a branch, 1.27.1.1. 


The result is that you have created a branch, and the file you will have in your 
workspace is version 1.27.1.1. 


If the version you want to branch from is the highest-numbered version on its 
trunk or the branch (such as version 1.30): 


Checkout -m file : ## Gets version 1.30, the top of the trunk 
Checkin -f -v 1.30.1.1 file /## Creates a branch 
SCMAdmin -u -v 1.30 file d## Cancels your lock on 1.30 


Because you acquired a lock on version 1.30, and then checked in version 
1.30.1.1, you must do the extra step of releasing your lock on version 1.30, which 
is what SCMAdmin does. 


After creating a branch, you can perform all the normal functions, such as 
designating versions on the branch with symbolic names using NameVersions. 
Those versions can be retrieved when you check out by name, use SyncSources, 
and so on. You can check out versions for modification and check them back in, 
but you have to do so carefully. If you use Checkout only, you always get the 
highest-numbered version on the trunk. To get a version from a branch you must 
specify the version number or use a symbolic name: 


Checkout -v 1.30.1.5 file 


When you check out a branch version for modification, you can use Checkin 
without any special arguments to check that version in again. The new version 
will be checked in to the branch, and that version will be checked out again as a 
read-only file in your workspace. 
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Note the capital ‘N’. 


Class and member 
descriptions 


CHAPTER 2 WORKING IN THE AIX ENVIRONMENT 
CHECKING FILES IN AND OUT 


One good way to work on a branch is to name it. When you create the branch, 
pick a name like JohnsBranch to designate each new version on that branch. Use 
that name every time you check out the file (or a set of files you have branched). 
Also, every time you check in new versions of the files you have branched, 
designate the new version with that name. That way the name always designates 
the latest version on the branch you are working on. For example, assuming that 
the latest version of WorkFile.C is 1.17: 


Checkout -m WorkFile.C 
<edit the file> 
Checkin -v 1.17.1.1 -n JohnsBranch WorkFile.C 


This creates the branch. To later modify your branched version of the file: 


Checkout -v JohnsBranch -m WorkFile.C 
<edit the file> 
Checkin -N JohnsBranch WorkFile.C 


This checks out the latest version on the branch and checks in a new version, 
carrying the name JohnsBranch along to the new version. Use the uppercase -N 
because the name JohnsBranch already designates one version of the file, and 
you want to change the version this existing name refers to. 


palace orca Paar banana rar se pccregedpeceraace rigors ge: 


Leg eee, 


Check in class and member description files (*.d) in a Docs subdirectory. For 
example, if you have a header Foo.h that resides in $TaligentRoot/Taligent/ 
Platform/AIX then the corresponding description file Foo.d resides in 
.../Platform/AIX/Docs. 


NOTE For native builds in the MPW build environment, class and member 
description files (*.d) were usually kept in the source code directory itself. 
Because the AIX build environment uses automated tools to grab the files and 
format them, be sure to keep all *.d files in the /Docs subdirectories. 


In addition to Checkin and Checkout, other useful SCM tools and scripts include: 

# SyncSources—an optimized Checkout that does not check out those files for 
which you already have the correct version in your workspace. 

 CompareVersions—displays the difference between a file in your workspace 
against a file in the project. See page 24. 

ss ListVersions—reports the workspace version of each file in the current 
directory. See page 26. 

# NameVersions—associates a symbolic name with a set of files in an SCM 
project or project hierarchy. See page 28. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT INTERNAL TOOLS 


11 


12 CHAPTER 2 WORKING IN THE AIX ENVIRONMENT 
STARTING AND STOPPING THE TALIGENT APPLICATION ENVIRONMENT 


LOLOL TOLL LL EOE ERLE PE ETL ER EOE EAP ER CELE EL ORE ELE OE OLE ELEE ELL ELE EE ELE E CETL PLETE EEL OO EE EL OOCCE EOP LLL EL EOE ELE OOOO EEE AATEC ELELEE ERE LEEE EERE EEL LETTE OCLC LT EEE Ce 


STARTING AND STOPPING THE 
TALIGENT APPLICATION ENVIRONMENT 


To run a Taligent Application Environment program on AIX, you must currently 
execute the program on the Taligent AIX reference layer. 


Starting the layer To start the layer, run StartPink. 
Move to the directory containing StartPink. 


cd $TaligentSharedLibs 
Run StartPink. 
StartPink 


For more information, see “StartPink” on page 75. 


If StartPink is successful, you can start an application. For example, to run 
Macrame or SimpleText: 


The “&” runs the command ——- Macrame & 
in the background. SimpleText & 


SPELL ELL OLD ISLE IIIS ISSO O IED PE LLLLL ELL OL IL LP EL ILL LE LED D DLL OL LOL OSL LEME CLL LI CIEL LLL OPE OPI EE EPL IL OEE EOL LIED ELE OL LLL APO ELLIOL LILLIE LOLI Le 


Stopping the layer Run StopPink to safely stop the layer. For more information, see “StopPink” on 
page 75. 
Run StopPink to safely stop the layer. 


StopPink 


To restart the layer, rerun StartPink. 
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TALIGENT OPERATING SYSTEM PROGRAMS 


To run a Taligent Operating System program, you must transfer your program to 
an Intel-based computer, and explicitly start the program and system. 


Poe Eee eer ee eee rere rere rene reer ere reer errr eres ee Peete ieee eee eee r ere err e er terre rere terre ree rer rarer rere eter eee errr rere eee eer eee reer eee eee eee ee ee 


Transferring your 


program 


PRELIMINARY 


To transfer your program to an Intel machine, use ftp. 


Move to the AIX directory containing your program. 


cd $TaligentSharedLibs 


Run ftp. In this example, the target machine is chrome.Enter your password, 
when requested. 


ftp chrome 

Set the transfer type to binary. 

type binary 

Optionally, turn transfer feedback on to print “#” for every block transferred. 


hash 


Change your ftp working directory on the remote machine to the directory 
where you want to put the Intel binary. 


cd /home/mpogue/test 
Copy the file from your AIX workstation to the Intel machine. 


put Macrame 
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STARTING AND STOPPING TALIGENT OPERATING SYSTEM PROGRAMS 


Starting To execute on the Intel machine, use rlogin to remotely login. 


your program Run rlogin from your AIX workstation. Enter your password when 


requested. 
rlogin chrome 


On the remote machine, change to the directory containing the binary 
image you transferred. 


cd /home/mpogue/test 


Run rp to start your program. (rp replaces the runpink program previously 
used to load and run programs.) 


The “&” runs thé Program rp Macrame & 
in the background. 


{NOTE ‘To debug your program, use gdb. For information about gdb, see 
Chapter 10, “GDB” on page 149. : 


EPL O LENE CELE EE CELLET LOTT EL PPM POEL EL 


Stopping Use the UNIX kil] command to safely stop your program. 


voor pide Run jobs to list running programs. 
jobs 
[1] + Running rp 
Run kill to stop the program. 
% 1 kills the [1] program ———-—--——- kil] -9 %]1 


[1] Terminated rp 
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CHAPTER 3 


‘TALIGENT SCM TOOLS 


Before you start to use the Source Code Management (SCM) tools, run SetRoot — 
(layer) or NativeRoot (native) to set the environment variables that these tools 
depend on. Also make sure you have created a mirror of the SCM project by 
using SCMCreateDirectories. If you have not done this, follow the instructions in 
“Setting up for Taligent Application Environment” on page 3. 


Most of the SCM tools assume you are in the working directory of interest before es 
running the tool. For example, before working on the Albert project, change to_ ANS 
the Albert directory. | 


cd $TaligentRoot/Taligent/Portable/AES/Albert 
Then, check out all the files in the Albert project from one consistent build. 
Checkout -a -r -v D32.29 | 


At this point, you have all the source files for the Albert project that were 
checked out from their home in the SCM hierarchy. 


“NOTE Each user has a private snapshot of the system. When you build a 
project (or project hierarchy), everything is on the local file system— header files, 
export files, and executables. This is your workspace. 


The only way other that people can see your changes is if you check in your 
changes using Checkin and NameVersions. Others can then see your changes in 
the next system build, or when they directly check out and build your project. 


ig NOTE AIl Taligent tools require that the filename argument be the last 
areument on the command line; all options must precede filename. 
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Seecieets 
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The system of symbolic names (used by NameVersions and the other tools) is 
implemented using a file called names in a subdirectory called .TaligentSCM 
(note the initial period) that is created in the repository and in your workspace. 
There is one names file per directory in the repository. Normally this is invisible 
to you. However, there are several considerations that you should be aware of: 


« The names file in the repository is the final word about symbolic names for 
that directory. Files in workspaces are local copies of the file in the 
repository. If the local file's last-modified date and time are newer than the 
file in the repository, then its contents are used. If the file’s date and time are 
older, a fresh copy is checked out. This is all done internally—you never see 
it. However, this means that the clocks of the machines on the network 
should be synchronized, or at least very close. 


# The names files are controlled by SCM, just like your source files. This 
prevents corruption that can occur if two people run NameVersions at the 
same time in the same directory. If two people do step on each other, one of - 
them gets a message that the “names file could not be checked out.” If this 
happens, just rerun NameVersions. 


« Because of the locking mechanism used by SCM, two NameVersions processes 
run by users with the same name can cause corruption of the names files. This 
_ can happen if you run NameVersions twice in parallel on a single machine, or 
anywhere on the network, using the same login name. 


CAUTION Do not run two NameVersions commands anywhere on the net at the 
same time with the same user ID. 
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CHECKIN 

CHECKIN 

Checkin submits your files into the SCM repository. Run Checkin for all project 

files that you checked out for modification. 
syntax Checkin [-n Name | -N Name] [-i | -I [-b] ] [-v version] [-a] (-C] [-f] [-m] 

[-r] [-q] £€-D] L filename...) 
Arguments —a | all: Check in all files in the workspace directory into the corresponding project 
directory. Use —a in place of filename. 

—b binary: Declare the checked in files as binary. Suppresses header substitution 
on the magic strings during checkout. Only works with -i and —I. 

—C Comment: Suppress comments strings for all files that are checked in; all files 
will have empty comment strings for that version. Checkin does not read 
standard input. 

—D debug. \nclude debug information in the output for debugging Checkin. 

—f force: Force Checkin to use a new version, even if the files are unchanged. 

| initialize: \nitializes a new file (the first version) in the project directory when a 
file is not already in the project. An error occurs if your working directory has 
no corresponding project directory. 

—| Initialize: \nitializes a new file and creates a project directory if none 
correspond to this working directory. Note: the parent of the working 
directory must exist in the project. 

—m modify: After checking the file in, check it out for modification. 

—n Name Check in the files and designate the symbolic name Name as the new version. 
see “NameVersions” on page 28 for more information about symbolic 
names. 

—N Name Check in files and designate the symbolic name Name as the new version, 
even if another version of the file already has that name. 

—q quiet: Suppress commentary (but still report errors). 

—T recursive: Run this Checkin command in this directory and recursively down 
the subdirectories in the workspace. 

—Vv version version: Specifies a particular version of each file. version can be a version 
number (like 1.4). 

filename The name of file in the corresponding project directory. Separate multiple 


filenames with white space. Use —a when you want all the files in the project. 
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CHECKIN 


Usage 


Comments 


Messages 


Prompt for comment ——— 


Comment 

End the comment 
Not checked in 
Not checked in 
Normal check in 


Before using Checkin, change to the directory in your workspace that contains 
the file you plan on checking in. For example, to check in the files from the 
Tokens project, change to your corresponding Tokens directory: 


cd $TaligentRoot/Taligent/Portable/OES/Tokens 


After checking in the file, Checkin retrieves a read-only copy for you. If you want 
to keep your lock on the file, use —-m to check the file in, and then immediately 
check out again for modification. 


Checkin -m filel.C 


Checkin prompts for a comment that applies to all files that are checked in. 
Checkin reads the comment from standard input so you can redirect to it from a 
file. If you want a separate comment for each file, run Checkin separately for 
each. 


single period or Ctrl-D. Be sure to avoid the common mistake of pressing Return 
and endlessly waiting for a new prompt. 


After Checkin submits a file, it displays a message indicating the file’s status and 
new version. The three file-status messages are: 


x Checkin—a normal check in 
# new—a new file 


# revert—the file reverted to the previous version because the file is identical to 
that version 


When you use —a to check in all files in the current project, Checkin prints a 
warning for files not checked out, but continues checking in the rest of the files. 


d## enter log message, terminate with single '." or CTRL-D (end of file) 
This is the user-entered comment text. 


d# Checkin: ERROR: foo.C is NOT checked out for modification by arn 
d## Checkin: ERROR: bar.C is NOT checked out for modification by arn 
checkin file.C,1.10 


For recursive check ins that use —r, the listing looks the same, except that there is 
an additional message for each project that it traverses. 


dt recursively checking in for /home/.../Toolbox/Tokens... 


If you attempt to check in a file that has never been checked in, Checkin displays: 


HHHF Checkin: WARNING: "file.C" is not part of the current project 
dHHF if "“file.C”" is a new file, use the -i/-I option with Checkin 


As the message says, you should include —i to indicate an initial version of the file. 
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New files or projects 


Checkin messages 


Examples 


CHAPTER 3. TALIGENT SCM TOOLS 
CHECKIN 


To add a new project to the existing hierarchy, such as TestWindowServer, a new 
sub-project of the WindowsServer project: 


Create the directory on your local file system if you have not done so already. 
Copy all the source files and TestWindowServer.PinkMake into the directory. 


Move to that directory and check in the files. Include —a to check in 
everything, and —I to create the project directory and initialize the files. 


% Checkin -I -a 


——___ ## Checkin - Creating rcs dir "/Repository/tools/Checkin/test”... 


new foo.C,1.1 
| new bar.C,1.1 


Check in files and designate the symbolic name ReadyForBuild as the newly 
checked-in version: 


Checkin -n ReadyForBuild filel.C 


Check in files and designate the symbolic name D34.FINAL as the newly checked- 
in version, even if another version of the file is already designated with that 
name: 


Checkin -N D34.FINAL files... 


Force a new version to be checked in even for files that have not changed 
(otherwise unchanged files revert to the previous version): 


Checkin -f -N D35.FINAL files... 


Check in all the files in the current directory and immediately check them out 
for modification: 


Checkin -m -a 
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CHECKOUT 


syntax 


Arguments 


CEPT EE. 


Pe 


rPseraceree: 


Checkout retrieves files from the SCM directory hierarchy (the source code 


databases) and puts them into your directory hierarchy—your working directory. 


Checkout [-a] [-m] [-c] [-r] [-o outFile] [-q] [-D] {-v version.. | -latest} filename... 


—D 


—latest 


—m 


—0 outFile 


—V version 


filename 


You must specify either - latest or -v. 


~ all: Check out all files from the corresponding project directory into the = 


workspace directory. Use —a in place of [filename...]. 
cancel: Cancel the check out of files checked out for modify. 
debug: \nclude debug information in the output. 


Check out the highest numbered version on the trunk. You must specify either - 
latest Or -v. 


modify: Check out the files for modification. Only one person can have a 
particular version of a file checked out for modification. 


output: Write the checked-out file to outFile instead of its own name. Use this to 
make a temporary copy of some version of a file without disturbing the copy in 
your workspace. For example, to get version 1.5 of Bundles.C and save it to 
Bundles Temp: 


Checkout -v1.5 -o BundlesTemp Bundles.C 
You cannot use —0 with —m, -p, —r, -a, -C, or with more than one filename. 


Write the checked out file to stdout instead of a file on disk. You cannot use —p 
with —m, —0, -1, —a, —C, or with more than one filename. 


quiet: Suppress commentary (but still report errors). 


recursive: run this Checkout command in this directory and recursively down 
the subdirectories in the project. 


version: Specifies a particular version of each file. version can be a version 
number (like 1.4) or a symbolic name (See “NameVersions” on page 28). If you 
specify multiple -v arguments, Checkout behaves as if you gave multiple 
commands, one for each symbolic name (version), in the order given. 


You must specify either -v or -latest. 


The name of file in the corresponding project directory. Separate multiple 
filenames with white space. Use —a when you want all the files in the project. 
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Usage 


Messages 


Checkout messages "4 


Locked revisions 


PRELIMINARY 


CHAPTER 3 TALIGENT SCM TOOLS 
CHECKOUT 


Before using Checkout, change to the directory in your workspace to which the 


corresponding files will be checked out; the directory corresponding to the 
project hierarchy where the file resides. For example, to check out the files from 
the Tokens project, change to the corresponding Tokens directory: 


cd $TaligentRoot/Taligent/Portable/OES/Tokens 
After Checkout retrieves a file, it displays a message indicating the file’s status and 
the version that was checked out. 


% Checkout file.C simple.C hello.C 
readonly file.C,1.5 
readonly simple.C,1.9 


_ readonly hello.C,1.5 


Occasionally when you attempt to check out a file, Checkout tells you that 
someone else has the file checked out for modification. For example, if Arn has 
file.C is checked out, Checkout responds: 


co error: revision 1.8 already locked Dy “arn" 


There are several things you can do when you get this message. 


Ask the other user to either check in or cancel the check out of the file. This is the safest procedure. 
To cancel a file checked out for modification: 


Checkout -c file.C 


Check out another version of the file on a branch. You can use Checkout to check out the file 
readonly with the intent of checking it back in on a branch. See “Check in files 
and designate the newly checked-in versions with the symbolic name ap_latest, 
even if another version of the file is already designated with that name (see 
“NameVersions” on page 28 for information about symbolic names):” on page 9 
for specific information. 


Change the access permission of the file. ‘The mro script (modify-read-only) changes the 
access permission for you. To avoid conflict with your coworkers, use this 
sparingly. It is easy to forget that you changed the file access. The following week 
you might wonder why you are the only one in the group who can build your 
project (or the only one who can run anything). 


mro File.C 


ListVersions can help track down some of these problems. See “Latest” on page 
26 for more information. 
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COMPAREVERSIONS 


Examples 


Note that 


Check out the latest versions of file.C to the workspace for reading only: 
Checkout file.C 

Check out version 1.8 of each file: 

Checkout -v 1.8 file.C hello.C simple.C 


Check out all (—a) the files in the project directory out into the workspace 
directory. If a version of a file is designated as Master.55, Change.187, or 
Change.189, then check out the last version specified on the command line 
(Checkout handles this internally as if separate commands were issued): 


Checkout -a -v Master.55 -v Change.18/7 -v Change.189 


Get all sources for the D34.FINAL build. Check out all the files in the project 
directory with a symbolic name, and recurs to all subprojects in the project. 


SyncSources does —-—- Checkout -v D34.FINAL -a -r 


the same thing, but is 
quicker 
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- Syntax 


Arguments 


CompareVersions displays the differences between files in your workspace and 
files in the project. It can also compare two sets of files designated with symbolic 
names in the project against each other. 


CompareVersions [-h] [-nnn] [-latest | namel [ name2 ] ] 


-h —S—Sseadings: suppress the column headings. = 


—latest latest: Compare the files in your workspace against the latest versions of those 
files. Latest means highest-numbered on the trunk. For this option, the left 
column of the report contains the files in your space, and the right contains 
the latest versions in the project. 


—nnn The columns to include; the default is —123 for all three columns. For example, 
| —1 outputs only column one, —2 only column two, and —23 outputs both 
columns two and three. Omitting a column suppresses all characters for that 
column—no spaces, no tabs. 


name? name2 Compare the files and versions designated by name? against those designated 
as named2, and report the similarities and differences. Omit name2 to compare 
against the current files in your workspace. Either name can be a 
NameVersions symbolic name. See “NameVersions” on page 28. 
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Usage 


Examples 
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COMPAREVERSIONS 


CompareVersions prints a report in a three-column format.In the following 
example, version 1.4 of Jungle.C is designated with the name D34.FINAL. No 
version of Jungle.C is designated D35.FINAL; while the opposite is true of Foo.C 
version 1.8. Both names designate the same version of MyFile.C version 1.4. 
Changing.C has one version designated D34.FINAL, and a different version 
designated D35.FINAL. 


Files that have a version Files where the same Files that have a version 


designated as name7, but no version is designated by designated as named2, but no 
version designated by name2 both symbolic names version designated by name? 
The file —----- _D34.FINAL SAME D35.FINAL ~<@———-------—-_ The file 
specified by Jungle.C,1.4 | specified by 
name1 | Foo.C,1.8 name2 
MyFile.C,1.4 
Changing.C,1.14 Changing.C,1.18 


Files with two different versions designated by both 
names appear in both the left and right columns 


Compare the files and versions designated with D34.FINAL against those 
designated with D35.FINAL, and report the similarities and differences. 
CompareVersions D34.FINAL D35.FINAL 


When you provide one name only, CompareVersions compares that name against 
the files in your workspace. In this case, the right column is labeled (current). 


CompareVersions D34.FINAL 


‘Compare the files in your workspace against the latest versions of those files—the 


highest-numbered on the trunk. 


CompareVersions -latest 
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LATEST 
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syntax 


Arguments 


Examples 


syntax 


Arguments 


Latest reports the latest trunk version of files in the project directory. Unlike 
ListVersions, which reports the version of the files in your directory, Latest 
reports on the files in the repository. 


Latest [-r] [fi/]ename..] 


—l recursive: operate recursively through workspace directories, skipping project 
directories that are not in the workspace. 


The name of a file in the corresponding project directory; you can specify 
more than one. Omit filename to report the latest version of all files in the 
current workspace directory. 


Report the latest trunk workspace version of all files in the directory: 


Latest 


Report the latest trunk workspace version of each named file. 


Latest filel.C file3.h 


ALAA E SEERA SIRES HERES A RENE 


ListVersions reports the workspace version of each file in the current directory. 
It also tells you which files are checked out for modification. 


ListVersions [-c] [-m] [-n] [-x] [+c] [+m] [+n] [+x] [-r] [fi]ename..] 


Dash (—) options combine to suppress listing of multiple categories. Plus (+) 
options combine to list multiple categories. 


—¢ —«OOmittfiles checked out read-only. = 


+C Only list files checked out read-only. 

—m Omit files checked out for modification. 

+m Only list files checked out for modification. 

—n Omit files not in the project. 

+n Only list files not in the project. 

—f Recursive: operate recursively through workspace directories, skipping 
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LISTVERSIONS 
—X Omit modify-read-only (mro) files. 
+X Only list modify-read-only (mro) files. 
filename The name of file in the corresponding project directory; you can specify more 
than one. Omit filename to get the versions of all files in the current 
(workspace) directory. 

Usage ListVersions looks for the $Revision$ tag-line at the beginning of each file in 
your working directory (SCMInsertHeader inserts this line). If ListVersions 
cannot find the line, it prints a warning and attempts to figure out what the 
version Is. 

The report contains the filename, the version number of the file in the 

workspace, and one trailing mark: 

(blank) File is checked out for reading only 

+ File is checked out for modification by you 

# | File is MRO: workspace version is writable, but you do not 
have that version checked out for modification 

<notin project> ‘File is not in the project (there is no corresponding file in 


the repository) 


Binary files have a question mark (?) instead of a version number because the 
version number cannot be known; binary files do not contain the $Revision$ tag- 
line. | 


Examples To report the version of file.C in your current working directory: 


% ListVersions file.C 
ListVersions ————- file.C,1.1 


message ; 
To report all files in the current directory, omit the filename. 


% ListVersions 
ListVersions ~ filel.C,1.1 
messages file2.C,1.2+ 
_ file3.h,1.2<not in project> 


Report the workspace version of all files except those not in the project, or those 
that are modify read only: 


ListVersions -n -x 


Report the workspace version of all files in the directory that are checked out for 
modification, or that are modify-read-only: 


ListVersions +m +c 
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NAMEVERSIONS 

NAMEVERSION 
NameVersions associates a symbolic name with a set of files in an SCM project or 
project hierarchy. It can designate a name, report what versions are designated 
with a name, display all names that designate any version of a file, and delete 
names. You can use the symbolic name when checking files out. 

syntax NameVersions [-c | -C | -1 | -L | -v version | -V version | -f | -d] 

[-r] symbolicName [ filename...] 
Arguments -c current: designate the current version(s) of the file(s) in your workspace with 
symbolicName. 

—C current. same as —C, but override an earlier definition of the symbolic name. 

—d delete: remove symbolicName So it does not designate any version of the files. If 
you omit filename, the symbolic name is completely deleted so it does not 
designate any version of any file. 

—f find: find versions designated with symbolicName. Display the version number of 
the files that the name designates. Omit symbolicName to display all the names 
that designate any version of any file in the current directory. 

—1 latest: designate the latest version(s) of the file(s) in the project with 
symbolicName. This option does not look at files in your current directory, it only 
refers to the corresponding SCM directory. 

Note, this option can cause problems because latest means the highest- 
numbered on the trunk, not the most-recently checked in. Avoid this option. 

—L latest: same aS -1, but override an earlier definition of the symbolic name. 

-r recursive: operate recursively through workspace directories, skipping project 
directories that are not in the workspace. 

—-V version version: designate symbolicName to the version of the files. version can itself be 
a symbolicName. 

—-V version version: same as —V, but override an earlier definition of the symbolic name. 

filename The name of file in the corresponding project directory; you can specify more 


than one. Omit filename to specify all files in the current workspace directory. 


The lower-case options (—c,-l, and —v ) let you designate a version with a name if 
that name does not currently designate any versions of the files, but these options 
do not let you change what version an existing name designates. The upper-case 
options let you change an existing name. oe 


In the lower-case forms, if symbolicName already designates any version of any of 
the files you are applying it to, NameVersions stops and reports an error, and no 
changes occur. If applying the name to one file is not allowed, then it is not 
applied to any of them. 
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Modes of operation 


Binary files 
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NameVersions names versions of files so that you can refer to the named set of 
files for checking in or out. For example, if each engineer designates their 
project ReadyToBuild when they are done, one person can later check out the 
entire project by that name and perform a complete build. 


When you change what version of a file (or set of files) a symbolic name 
designates, that does not affect any other files which may have versions 
designated with that name. For example, Winner.C version 1.2 and BigWin.C 
version 1.5 are both designated with the name ReadyToBuild. If you run 


NameVersions -V 1.7 ReadyToBuild BigWin.C 


the result is that the name ReadyToBuild is moved to version 1.7 of BigWin.C. 
However, this does not affect which version of Winner.G, or any other file, is 
designated with that name. 


NameVersions has five basic modes of operation: 


# Designate the current versions in the current directory (-c) with a name 
# Find a name(-f) 

« Designate the latest version (-1) of a file or files with a name 

# Designate a particular version (—v) of a file or files with a name 

# Delete a name (-d) 


NameVersions does not designate any version of a binary file when you use —c or 
—C. By definition, the SCM tools cannot tell what version of a binary file is in your 
workspace. However, if you include —b in addition to —c or -C, NameVersions 
designates the latest version of any binary files with symbolicName. For example, if 
you have the source file MunchData.C and a binary file TheData in a directory 
and you issue 


NameVersions -c BuildVers MunchData.C TheData 


you will get a warning telling you that NameVersions could not tell what version 
of The Data is in your current directory, and no version was tagged with the name. 
If you issue 


NameVersions -b -c BuildVers MunchData.C TheData 


then the current version of MunchData.C will be designated, and so will the latest 
version of TheData. In this manner you are telling the tool what version you 
have. You are specifying that you have the latest version, so that's the one you 
want designated with the name. 


In this context, the latest version is the highest-numbered version on the trunk 
(no branches). This is the same version reported by Latest. | 
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To name only two files: Avoid the common 
NameVersions —c Defiant.1042 Filel.C File2.h DO eh 
inadvertently omitting 
To associate Defiant. 1042 with the latest versions of all the files in the project: the symbolic name 
NameVersions —1 Defiant.1042 ee ae 
multiple filenames. 


To associate Defiant. 1042 with the with the 1.4 version of File1.C: 
NameVersions —v 1.4 Defiant.1042 File1.C 


To recursively find versions designated Defiant. 1042 in all files, from the current 
project directory down, and designate those versions of those files D37. 1: 


NameVersions -r -v Defiant.1042 D37.1 


To designate to version 1.4 of file3.C with the name Defiant. 1042, even if that 
name already designates another version: 


NameVersions -V 1.4 Defiant.1042 file3.c 

To list the files associated with Defiant. 1042: 

NameVersions —f Defiant.1042 

If you no longer need a symbolic name, remove it with —d: 
NameVersions -d Defiant.1042 

To delete a particular file from a name: 


NameVersions -d Defiant.1042 file3.c 
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NativeRoot initializes your environment for Taligent Operating System (native) 
by setting the value of $TaligentRoot and several related shell variables. 
$TaligentRoot is the directory from which all your Taligent source directories 
and files descend. To initialize your environment for the layer environment, use 
SetRoot (see page 38). 


CAUTION Never set $TaligentRoot directly—instead, always use NativeRoot 
because it also sets other important related variables. 


NativeRoot [-c] [-1] directoryName 


-C Create: Make all the directories needed for installation. 
-] Latest: Use the latest directory structure available. 
directoryName The directory from which all your Taligent files will descend 


NativeRoot ~/Work 
NativeRoot -0 ~/Work 


SCMAdmin reports and sets the attributes of a file, and breaks another user’s lock « 
on a file. 


SCMAdmin [-v Version] [ rcsOptions ] filename 


‘resOptions -—S«Optionstopasstores. = = | . 
-v Version Administer this version of the file; can be a number or symbolic name. 


filename The name of file in the workspace directory 


Unlock the version of the file designated D34.FINAL; -u is the unlock option to 
break the lock on file.C. (Be sure to notify the owner of the lock first.) 


SCMAdmin -u -v D34.FINAL file.C 

Mark file.C as binary: 

SCMAdmin -ko file.C 

Mark file.C as a normal text (non-binary) file: 


SCMAdmin -kkv file.C 
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SCMCreateDirectories examines the project and creates corresponding 
directories in your workspace. 


syntax SCMCreateDirectories [-d] 


Arguments —d Refrain from creating directories named “Docs” (note the initial capital). 
These are the class and member description files directories. Using this 
option you can create a workspace which does not include those directories. 
This option is for use by Pre Build and Integration teams (PBls) and the build 
room, because having those directories slows down their check out 
operations. 


Usage SCMCreateDirectories creates directories recursively starting with your current 
directory. That is, if you start it from $TaligentRoot/Taligent/NetComm, it creates 
directories that exist in the project below $TaligentSCMRoot/Taligent/NetComm. 
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SCMDiff uses diff to compare a file in your workspace against a version of that 
file in the project. 


syntax SCMDiff [ -v version [ -v version2] ] [ diffOptions ] filename 
Arguments diffOptions ' Options to pass to diff. 
-Vv Version Compare the workspace file against Version. Version can be a version 


number or a symbolic name. 
-v Versioni-v Version2 Compare these two versions of the file. 


filename. The name of file in the corresponding project directory. If you omit —v 
options, compare the current working file against the locked version of 
that file, or against the latest version on the trunk if you do not have it 
locked. - | 


Examples Compare version 1.3 of file.C against the version designated with D34.FINAL: 
SCMDiff -v 1.3 -v D34.FINAL file.C 


Compare file.C in your workspace against the latest version on the trunk. Pass -c 
to diff to supply context around the differences: 


SCMDiff -c file.C 


Compare file.C in your workspace against the version designated with 
D34.FINAL. Pass -b to diff to ignore differences in indenting and spaces: 


SCMDiff -b -v LastDRelease file.C 
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SCMFETcCH 


SCMFETCH 


syntax 


Arguments 


Usage 


SCMFetch is used by xcdb to get a copy of a source file for debugging when xcdb 
can’t find a copy on its own. 


SCMFetch [—build] [-xfile fname] [-—xpath dirname] [-which] [fi/ename..] 


—build Update the SCMFetch cache. 

—-which Report how SCMFetch found the file you asked for, rather than actually 
producing its contents on standard output. 

—xfile fname. Exclude the file fname when updating the cache 

—xpath dirname Exclude the directory dirname, and its children, when updating the 
cache. 

filename Look for filename in the source code hierarchy. If found, echo its 


Character content to standard output (console). 


SCMFetch maintains a cache of the files in the project; the cache contains the 
containing directory name of each file in the project. It maintains this cache in 
the root directory of the SCM repository, $TaligentSCMRoot. 


When the debugger calls for a file, SCMFetch searches for it in this order: 


# If $TaligentSCMFetchPath is set, SCMFetch looks in those directories for the 
file. You can specify more than one directory by separating them with colons: 
/home/ joe/dirl:/home/ joe/dir2 

« If $TaligentSCMFetchPath is not set, or if the file is not in ieee directories, 
SCMFetch consults its cache for the project directory that contains the file. It 
then looks for the file in your corresponding workspace directory. 

# If the file is not found in the workspace, SCMFetch checks the file out from 
the repository. If the file $TaligentRoot/TaligentSCM/BuildName exists, then 
SCMFetch uses that file's contents as a version name to check out. Otherwise it 
checks out the latest version on the trunk. 


The directory that the file belongs in must exist in your workspace. Make 
sure your workspace contains all directories with SCMCreateDirectories. 


# If the file is not found in the repository, SCMFetch writes an error message to 
stderr and exits. 
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Sometimes there is more than one file in the world with the same name. To 
ensure SCMFetch finds the file that you want, set $Tal igentSCMFetchPath to 
include the file’s directory. This ensures that SCM Fetch searches the directory 
before searching the cache. 


When SCMFetch checks a file out from the repository, it uses the BuildName file to 
supply a -v version to Checkout. If you are working with a version that does not 
match the version in BuildName, manually check out the versions of the files that 
you are using so SCMFetch uses the ones in your workspace. 


The -build option builds a cache file. When you build a cache, use —xfile and 
—xpath to prune the cache of unwanted directory and file entries, and to ensure 
that the correct file appears when two files in the repository have the same name. 


Use —xfile nnn to omit from the cache those files whose names end with the 
pattern nnn. SCMFetch compares the pattern against the full path name of each 
file before adding the file to the cache. You can supply more than one -xfile. 


Use -xpath ppp to omit from the cache those directories whose names end with 
the pattern ppp. SCMFetch compares the pattern against the full path name of 
each directory. If it matches, then SCMFetch omits that directory and all its 
subdirectories. You can supply more than one -xpath. 


Assume that you have directory Sources/Tools in your repository, and that 
directory has some files in it. To split Tools into DevelopmentTools and 
AnalysisTools, you cannot just delete the Tools directory because then you could 
not build versions from before the split. To keep SCMFetch from finding the files 
in Tools: | 


-xpath /Tools 


Assume that Scripts is another directory containing files. To split it and put some 
of the files in the new directory ExtraScripts, you have to make sure that the old 
file do not appear to SCMFetch: | 


-xfile /Scripts/oldl -xfile /Scripts/old2 


The patterns in the example start with slashes because they are matched against 
filenames like Sources/Scripts/oldi and Sources/ExtraScripts/oldi. Without 
the leading slash, both of these would match and would both be omitted. 
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syntax 


Arguments 


Usage 
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Syntax 


Arguments 


Usage 


SCMInsertHeader prepares files for initial check in to SCM. It removes old SCCS 
(Source Code Control System) tag lines from previous sessions, and it inserts an 
SCM $Revision:$ tag-line. It ignores files that already have a $Revision:$ or 
$Header: $ header-tag. 


SCMInsertHeader f7/]ename... 


filename The name of file in the corresponding project directory; you can specify more 
than one. 


If filename contains a SCCS tag lines, SCMInsertHeader uses the comment leader 
on those lines for the new SCM tag line. Otherwise, if there is no SCCS tag line, 
SCMInsertHeader guesses a comment based on the filename: 


# // comments for .C, .c, .h, and .PinkMake files 
z d# comments for .Make files, and for files ending with Makefileand makefile. 


If file does not contain a SCCS tag, and if SCMInsertHeader cannot determine 
which comment leader to use from filename, SCMInsertHeader does not modify 
the file and a prompt instructs you to add an SCM tag manually. 


SCMInsertHeader modifies the file in place; it does not make a copy. 


SCMLog displays the revision history of the file. 


SCMLog [-v version] [ rlogOptions ] filename 


rlogOptions Options to pass to rlog. 
- -V version Compare the workspace file against the specified version. 
filename The name of file in the workspace directory. 


SCMLog takes the same arguments as rlog; see man rlog on-line for more details. 
Unlike r1og, however, you cannot pass a range of version numbers to SCMLog, only 
a single version number or name, and you must use —r to pass ita version _ 
number. 
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SouiNoeatin. 


SCMNormalize produces a normalized form of either a file or a directory name. The 
normalized form is a full pathname, not a relative pathname, and starts with /mnt if 
the real directory starts /tmp_mnt/mnt. 


syntax SCMNormalize [filename | directoryName] 

Arguments directoryName The name of a directory in your workspace. 
filename The name of the file in the workspace. 

Usage SCMNormalize prints the pathname to standard output. 


Use SCMNormalize when setting the shell variable $TaligentRoot, which must be 
in normalized form in order for the SCM tools to work properly. SetRoot and 
NewRootCommands use SCMNormalize to set $TaligentRoot for you. 


Examples Here are two examples of SCMNormal ize: 


% SCMNormalize ~tsoi 
SCMNormalize result —- /home/tsoi 


% SCMNormalize /usr/taligent/bin 
SCMNormalize result — /usr/talilocal/taligent/bin 
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SCMPRoyECTFILE. 


SCMProjectFile reports the full path name in the $TaligentSCMRoot repository of 
a file in your working directory. It can also report the path to the corresponding 
working directory’s path. 


syntax SCMProjectFile [filename] 
Arguments filename -—“‘ The name of the file in the workspace directory. This file does not have to exist 


in your workspace. If you omit filename, it returns the full pathname of the 
corresponding project directory. 


Usage Use SCMProjectFile when writing scripts that need pathnames. SCMProjectFile 
prints the pathname to standard output. 


If the current directory does not descend from $Ta1i gentRoot, SCMProjectFile 
reports an error and exits with nonzero status. 
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SETROOT 


SetRoot initializes your Taligent Application Environment environment by 
setting the value of $TaligentRoot and several related shell variables. | 
$TaligentRoot is the directory from which all your Taligent source directories 
and files descend. To initialize your environment for the ae environment, use 
NativeRoot (see page 31). 


CAUTION Never set $TaligentRoot directly—use SetRoot instead because it also 
sets other important related variables. 


Syntax SetRoot [-0] directoryName 


Arguments -0 ‘Optimize: turn optimization on for your compiles (affects the setting of 
$Compi leOptions) 


- directoryName The directory from which all your Taligent files will descend 


Examples SetRoot ~/Work 


~ SetRoot -0 ~/Work 


acc leaned 


SyncSources compares the files in the workspace against those versions of the 
files in the project designated with a specified symbolic name, and checks out the 
files necessary to get your workspace in sync with the project. 


Syntax SyncSources [-a] [-e] [-r] [-latest] [-s] [-d] [-w] 
{ syncName | -v syncName [-v syncName].. } 


Arguments -a SO all: re report on nfiles that ; are the s same e and therefore are e not checked out, ‘and Jon 
files in the project: that do not have a version named syncName. 


-d delete: delete files in ‘the workspace that are not in the repository (not 
controlled). It executes rm commands unless you also include -s, then it 
prints the rm commands to standard output. It does not generate rm 
commands for directories. 


-e - exhaustive: report files that al are. in n your workspace and which a are @ not it in ithe | 
project (a condition necessary for a clean build). -e also retrieves the same 
files as —a. 

—latest Designates the latest versions of files, not just those which a are 'e designated bya a 


symbolic name. In this context, the /atest version is the highest-numbered 
version on the trunk (no branches). This is the version that Latest reports. 
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-f recursive: operate recursively through subdirectories in your workspace, 
silently skipping subdirectories in your workspace that aren't in the project, 
and reporting subdirectories that are in the project and not in your workspace. 


-§ script. generate a script on standard output which, if executed, would perform 
the check outs. 


—v syncName The symbolic name that designates the versions of the files to compare 
against the files in your workspace. If you include more than one syncName, 
SyncSources behaves as if you gave multiple commands, one for each 
sida name, in the order given. 


SyncSources checks out all files with a version designated with syncName, similar 
to Checkout -r -v syncName, but skips the files for which you already have the 
right version. In this case, it is an optimized check out. 


SyncSources does not overwrite files you have checked out for modification, or 
modify-read-only files; for those it reports an error. 


SyncSources reports the reason for each check out that it does, such as whether 
the file was missing in your workspace, if was there already, what version was 
there, and what version is being checked out. 


Check out and sync all files designated Master.55: 
SyncSources Master.55 | 

The —v option is required for multiple versions, like this: 
SyncSources -v Master.55 -v Change.187 


Checks out and synchronizes all (—a) the files in the project directory out into the 
workspace directory. If a version of a file is designated Master.55, Change.187, or 
Change.189, then check out the last one specified on the command line 
(SyncSources handles this internally as if separate commands were issued): 


SyncSources -a -v Master.55 -v Change.187 -v Change.189 
Check out the latest versions of the files in the workspace directory: 


SyncSources -latest 
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CHAPTER 4 


‘THE BUILD ENVIRONMENT 


The Taligent AIX build environment was designed to allow individual 
contributors to efficiently accomplish their work, to allow full-system (or major 
subsystem) builds—and to accomplish both in a similar fashion. Once you know 
how to do the first, the second is easy. This chapter focuses on how you, the | | 
individual contributor, use the build environment. P . re ee 


Taligent uses these terms when describing the build environment: 


_ # Build—run the necessary tools to generate client and executable files in the 
proper order on any project or any project hierarchy. To accomplish this, 
each project (or project hierarchy) must have its own makefile. See 
“Makefiles” on page 43 for more information. 

« Chent files— headers and export files. 

# Header files (.h files)—files containing your C++ class definitions. 

# Export files (.e files) —files containing a list of all entry points in your shared 
library. Your clients link against .e files and the runtime system binds the calls 
to your shared library at run time. 


« Binaries—executable programs or applications that use shared libraries 
during execution. | 


# Shared libraries—Class libraries used by multiple programs are usually loaded 
dynamically at runtime. To build a shared library, compile your source files, 
generate your .e file, and link against other .e files. For building the layer or 
layer applications, use MakeSharedLib (see page 69 for more details). When 
building native, the link is handled automatically by Universal .Make. Intel, 
which calls Plink. 

# Executables—binaries or shared libraries. To build a program or executable, 
compile your source files and link against .e files using MakeSharedApp. Your 
source files must contain a main entry point. (See “MakeSharedApp” on 
page 68 for more details. ) 
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The Taligent Application Environment is a big web of interdependencies. To 
solve these interdependencies, the build process is occurs in four phases that first 
build all client files, and then build all executables. This automated process 
generates both client and executable files. 


Exports all public header The build process makes header files 

files for clients (*.h) by copying them from the project 
into a common directory where other 
projects (clients) can access them 


Compiles all .C files into .o 


files 

Combines all .o, and The build process makes export files 
generates .e files for (*.e) by compiling *.C files, combining 
clients them into one .o (or .a), and then using 


MakeExportList to generate the .e 
file (see “MakeExportList” on page 65) 


Generates all shared 
libraries and executables 


ats 


SES 


‘NOTE For Taligent Operating System builds, files currently have different 


extensions than those cited in the illustration: object files are *.ip, libraries are 
*.1ib, and export files are *.client.ip. 


To automate the build process, use makefile descriptions to specify the files to 
build, and use CreateMake to translate the makefile descriptions and to build the 
files. 


CAUTION The current build tools do not test to see if your component, 
application, or library has the same name as one used by the system. The build 
process will automatically overwrite the Taligent file with yours if you have a 
duplicate name. 
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The makefiles associated with each project are makefile descriptions, not standard 
makefiles. During a build, Makeit calls CreateMake to translate the makefile 
description to a standard-makefile. Makeit then calls make to analyze the 
dependencies. of the generated makefiles and update the project. Because 
makefile descriptions are source code, you can check them in to SCM; but, do 
not check in the generated makefiles. Makefile descriptions have filenames in 
the form Project.PinkMake, where Project is the name of the project or directory. 


J NOTE Chapter 6, “CreateMake,” describes makefiles in detail. 


Type of target, 


Bt at hie k Sen Eat ne ea cn te ail ites el aca ca Dcchiaekd Geeta dened common types 
a ae MMe OF INC 1aroer include Library, 
TypeOfTarget TargetName { Program, 
Label: . ParentObject, and 
FileList ------------  —s [de ntifies the build topic, typically SubProjectList 
Label: source, Link, or PublicHeaders 
FileList -————-—-—---____-___-__--_—---_--_- The files to process 


MELLEL EEE LE EEE LEER LL LE 


Library 


Program 


See SELLE LN LTE A ee 
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CreateMake generates different build rules for each type of target. Here are a few 
common target descriptions; for more, see Chapter 6, “CreateMake.” 


Generates rules to build a shared library. 


Library WidgetLib { —————————__ Build WidgetLib, also generates Widget.e to allow 

Source: z other Widget.h files to link in. 

Vides | Mgt is but from 

° ee fi 

PublicHeaders: Hest WOES 

WidGCU. re Export Widget. to allow other projects to use 
Link: . Widget objects 

TestFrameworkLib = a 

ToolboxLib promomennnnnnnennn, GDECHICAlly link with these files 


} 


Generates rules to build an application. 


Program ShowWidget { 


Source: | ~ at 
fe Og eaten tenner Il syst ecause there 
ShowWidget.C : Use all system libraries because 


is no Link label 
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ParentObject Generates rules to build and combine the source files. Frequently used to 
combine several projects into one larger library. 


ParentObject FooBarLib { ————— Generate FoobarLib.o to be ParentObject targets do 
source: included in the build of another not require a Link label 
Foo.C library _ because they are not 
Bar.C | linked 


publicheaders: 


Foo.h a 
Bar.h | Exported for clients 


SubProjectList A special type of target that lists all the sub projects that you want to build; it does 
not have a target name or any labels. Makeit uses this list when traversing the 
project hierarchy and only builds from those directories listed. 


SubProjectList { 


SubProjl Build SubProject1 and SubProject2, but ignore SubProject3, 
SubProj2 even though it is part of the project 


cael LOLOL LLL EEL ELE ECL EEC TE CELE LEELA EME CELE EEL COTTA EEL ELE ELLER E PLL RAE ELELEE EEE OEM EEC EEE L ER ELM PELE ELA LT ELE EL ERATOR CTRL EOE EEL ELS 


MAKEIT 


Once your have a makefile description, use Makeit to build your project. Makeit is 
: a specialized wrapper (or front end) to make. Makeit simplifies builds, provides 
consistency, and has the ability to traverse project hierarchies and convert 
makefile descriptions to real makefiles along the way. 
syntax Makeit [options] [Targets] 


Makeit only has a few options. If you specify any other options, Makeit passes 
them along to make. So in effect, Makeit has the same options as make. For 
information about Makeit and its options, see “Makeit” on page 66. 


If you omit options and targets, Makeit goes through each target in the build 
process (Includes, Objects, Exports, and Binaries), and builds the necessary 
dependencies. However, because Makeit is really a wrapper for make, it accepts 
any legitimate target in a makefile. | 


Makeit DemoApp 


A common mistake is to build one target (like the previous example), and not 
realize that Makeit is going to do a make on all subprojects of DemoApp—many 
of which do not have a target DemoApp. To prevent Makeit from building 
subprojects, include -c. 


Makeit -c DemoApp 


For more robust examples, see “Real life examples” on page 49. 
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Makeit passes any options it does not recognize. You can use this feature to pass 
options to make. Makeit passes arguments to options, and can override variables 
in makefiles. For example, to override the COPTS variable in the makefile: 


Makeit COPTS=-g Binaries 
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cigatnga makefiles | 


Universal.Make 


Other Global Targets 


When Makeit builds a makefile on the fly, it does so because either 
«: The *.Make file does not exist 
« The *.PinkMake file is newer than the *.Make file, or 
# The -M option forced automatic makefile generation. 


Makeit uses CreateMake to translate the makefile descriptions (*.PinkMake) to 
UNIX makefiles (*.Make). For more information, see “CreateMake” on page 60. 


PCCM LEO LCEK OD 


To prevent duplication in each makefile, and to allow more flexibility, CreateMake 
includes Universal .Make in every generated makefile (*.Make). 


_@ NOTE Each target platform has a separate version of Universal .Make. For 
native builds, the file is Universal .Make. Intel. 


Universal .Make contains global targets and rules. Some of the familiar global 
targets are: Includes, Objects, Exports, and Binaries. Other targets are useful 
because they are applied only to the projects in the build and not to every 
directory in the hierarchy. For example you can have a subsystem that is checked 
into SCM, but is not part of the build. These targets will not be applied to those 
projects. 


Global Target Task 


Clean Remove all . 0's, eS, s, and libraries that v were e built. 
Complete Expand into the standard targets: Includes, Objects, Exports, and Binaries. 
Makefiles Allows you to traverse the directory and rebuild makefiles as needed. 


The includes, objects, exports, binaries, and clean targets have lower-case 
synonyms, so capitalization is not required. 


‘-¢ NOTE Before you build anything with Makeit, follow the installation 
procedures in Chapter 2, “Working in the AIX environment” to check out a 
correct version of Universal .Make or Universal .Make. Intel into your 
$TaligentRoot/Taligent directory. 
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The {} bound variable 
references in shell scripts. 


The AIX build environment relies heavily on two types of environment variables: 


Pathname environment variables contain pathnames that are specific to each user. All the 
build tools and makefiles refer to the standard locations through environment 


variables. This allows you to define the location of your working directories. 


$TaligentRoot, set by SetRoot, is the basis for all other pathname variables. For 
example, here are two pathnames as set by SetRoot: 


setenv TaligentIncludes ${TaligentRoot}/PinkIncludes 
setenv TaligentExports ${TaligentRoot}/Exports 


Variable 


LIBPATH 
TaligentBATRoot 


TaligentBinaries - 
TaligentDefaultHomePlace 


TaligentExports 


TaligentExtension|ncludes 
Taligentincludes 
TaligentincludesDir 


TaligentLibs 
TaligentObsoleteincludes 


TaligentPlacesRoot 
TaligentPrivatelncludes 
TaligentRoot 
TaligentSCMRoot 


TaligentSharedLibs 
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Taligent shared libraries used during runtime. 


Root of the area where all BAT scripts, data, and results reside. 
BAT libraries, and servers go in the nontest (standard library, 
server, program) areas. 


Taligent runtime binaries. 


Repository for the current user’s home place (Only one user 
currently for the system.) The Workspace group will provide a 
better object API for getting access to the current user and storage 
areas related to that user in future releases. 


Taligent shared library interface files that developers link with to 
access faligent shared libraries. 


Directory containing interfaces to system extension developers. 
Main #includes directories used in Taligent builds. 


Base parent directory of all Taligent #inc1udes (this is the parent 
of $Taligentincludes, $TaligentExtensionIncludes, and 
$TaligentObsoletelncludes). 


Directory for certain nonshared libraries. 


Directory containing interfaces that should not exist in the SDK 
release but cannot, or that have not had their dependencies 
successfully removed. This directory will go away by SDK2. 


Repository where Places for the machine reside. 
Private # includes used internally. 

The base of everything in the build and runtime system. 
The repository for Pink source. 
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Variable 


‘TaligentSource 


TaligentSystemDataRoot 


TaligentSourceRoot 
TaligentSystemLibraries 
TaligentSystemPrograms 
TaligentSystemRoot 
TaligentSystemServers 
TaligentTemporaries 


TaligentTestLibraries 
TaligentTestPrograms 
TaligentTestServers 
TaligentTools 
TaligentToolsEtc 
TaligentUniversalMake 
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build, but is used by some tools that the Build room uses. 
TaligentSource is the root of the native and layer source tree; 
eventually there will be settings for Hoops, CompTech, and 
possibly more. 


Repository for system data files. These are typically configuration 
files, not first class user data such as movies, images, or sounds. 


Root of the Taligent source tree hierarchy. 
Repository for system software shared libraries. 
Repository for system software shared libraries. 
Root of the Taligent system software area. 
Repository for system software servers. 


Repository for temporary files until people use real Pluto 
temporary file support. 


Repository for system test shared libraries. 
Repository for system software shared libraries. 
Repository for the test servers. 

Internal tools. 

Additional internal tools, scripts, etc. 
Universal.Make file used in build system. 


Option environment variables contain the standard options to the standard tools that the 
build uses. Having the options in an environment variable allows you to change 
and experiment with certain options (like debugging options) without 
disturbing others. Never add options to the compiler (or to any build tools) in 
the makefile—use the environment variables instead. 


Makefile variables 
are acommon 
alternative to 
environment 
variables, but are 
disastrous in our 


Variable Options t build environment. 
‘CompileOptions =~=—-x1C. command line during builds as the options for building — 
Taligent code and default search paths to Taligent #includes. 
MakeSharedAppOptions MakeSharedApp as default options for building a Taligent shared 
library. : 
LinkOptions x1C link command line during builds. 
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© NOTE Occasionally a project requires a special option (such as working 
around a compiler bug). For special cases when the project cannot build or will 
not work unless it has a particular option, add the option to the makefile 
description file (*.PinkMake). To add an compiler option, add the following line 
to the *.PinkMake file: 


compileoptions: -NewOptions 
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SetRoot and 
NativeRoot 
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How to change 
environment variables 


environment variables 


SetRoot defines the standard values for all the environment variables that the 
Taligent build environment requires. You can review the complete SetRoot list of 
the environment variables (and descriptions) by looking at the /usr/taligent/ 
bin/NewRootCommand script. Always use SetRoot to initially set the variables and 
pathnames. If you need to change a variable, do so after running SetRoot. 


“NOTE  SetRoot is the layer command. If you are working on Taligent 
Operating System, use NativeRoot instead. For more information, see “Initialize 
your environment” on page 5 and “Prepare your environment” on page 6. 


AMELIA ALE AEE SERS AIS ATA ALK REALE EPP EK ER OEL EES ERS 


The easiest way to change an environment variable is to add to it. For example, in 
a shell script, to add -D__MYDEBUG__ as an option to the compiler: 


setenv CompileOptions "-D__MYDEBUG_ ${CompileOptions}" 


If you frequently add the same option, put the setting in a startup file. 


LPIERIPM LESS RPE ORSIL LEAST II ERED STILL APSELLER EES A ELRER SS 


It is easy to change the environment variables to customize your environment, 
but be careful not to get too carried away with additions. Remember, other 
people need to build your project too; do not become dependent on a particular 
-D you have defined in your environment variable. The system builds use the 
default options as defined in the BuildOptions file. 
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—— LIFE EXAMPLES 
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By now you should understand the organization of projects and have a 
fundamental grasp of how the build works. This section ties together everything 
you have learned by using several real life examples. 


NOTE Before you begin this section, make sure your initial set up is correct 
(see Chapter 2, “Working in the AIX environment”) including checking out the 
Universal .Make file. 
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A simple sanipie SimpleSample' is similar to Kernighan and Ritchie’s hello world program. This 
program is ideal for demonstrating how to create, build, and execute an 
application. 

How to create Create a directory named SimpleSample. You can create the directory 

SimpleSample anywhere on your file system; in your home directory is probably best. 


Create a source file hello.C and enter: 


#Hinclude <stdio.h> 
void main() 
{ 
printf("Hi there everybody! \n"); 
} 


Use your favorite editor to create hello.C . For custom features that can 
improve Emacs efficiency, see “Emacs” on page 162. 


Create a makefile description called SimpleSample.PinkMake and enter: 


program SimpleSample { 
source: 
hello.C // A single source file 
} 


The name of the *.PinkMake file must be the same as the name of the 
directory in which it resides. The example resides in .../SimpleSample. 


Zi Build SimpleSample using Makeit without any options or targets (See the 
section Makeit, “Default operation:” on page 22): 


Makeit 


NOTE When compiling for Taligent Operating System, NativeRoot 
automatically sets up your environment so that Makeit uses the -intel argument 
to generate Universal.Make. Intel instead of Universal .Make. 
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The build log 


Makeit messages 


The Includes phase 


The Objects phase 


-The Exports phase 


The Binaries Phase 


The Copy phase 


COonT EH OT 


19 
20 
21 
22 


23 


24 


What follows is the build log; yours should look similar. 


The first message is from Makeit stating that it did not find SimpleSample.Make in 
the project. Therefore, Makeit built a makefile from Simp]eSample.PinkMake. 
Line 3 is the CreateMake command that Makeit issued to create the makefile. 


dHHEF Makeit: No makefile found in ~/home/EeeDee/SimpleSample'. 
HEH However one will be built from ~“SimpleSample.PinkMake’. 
d## CreateMake > SimpleSample.Make; 


Since SimpleSample. PinkMake did not specify any public header files, Makeit and 


not build any include files. 


li 

d## Making "Includes" for "/home/EeeDee/SimpleSample". . 
## make -f SimpleSample.Make Includes 

i 


make: Nothing to be done for ‘Includes' 


Compiles hello.C to hello.o, and contains the make line that Makeit called. 


# 

d## Making "Objects" for "/home/EeeDee/SimpleSample”.. 
## make -f SimpleSample.Make Objects 

# 

## Compile hello.C to produce hello.o 


Did not build a shared library because SimpleSample did not build an export 
file. 


i 

d## Making "Exports" for "/home/EeeDee/SimpleSample"... 
d## make -f SimpleSample.Make Exports 

i 


make: ~Exports' is up to date. 


Creates the executable application by calling MakeSharedApp (as echoed from 
make). For more information, see “MakeSharedApp” on page 41 

i 

## Making “Binaries" for "/home/EeeDee/SimpleSample"... 

4 make -f SimpleSample.Make Binaries 


# 


MakeSharedApp -L. -L/usr/lib/dce -o SimpleSample hello.o /home/EeeDee/work/Expo 
rts/RuntimeLib.e /home/EeeDee/work/Exports/OpixLib.e /home/EeeDee/work/Exports/T 
oolboxLib.e /home/EeeDee/work/Exports/TimeLib.e /home/EeeDee/work/Exports/TestFr 
ameworkLib.e /home/EeeDee/work/Exports/HighLevelAlbert.e /home/EeeDee/work/Expo 


rts/LowLevelAlbert.e /home/EeeDee/work/Exports/AlbertPixelBuffers.e 


Copies the built application to $TaligentBinaries, the standard location for 
executable files, and leaves a copy in the current directory. 


SmartCopy SimpleSample /home/EeeDee/work/TaligentBinaries 
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How to execute When the build completes, execute SimpleSample program by typing its name at 
SimpleSample the UNIX prompt. It should look like this: 
% SimpleSample 
OPIX compile timestamp = Jan 22 1994, 08:25:22 —---— The Taligent AIX Layer prints a time-stamp 
Hi there everybody! 


: when it runs an application. 


“2 NOTE See “Starting and stopping Taligent Operating System programs” on 
page 13 for information about running the Simple Sample program on Taligent 
Operating System. 
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A faster build A slightly faster and more efficient way to use Makeit is to include the target 
name. For example, change SimpleSample to use a Taligent object, and then 
rebuild it. | 


Change hello.C to look like this: 


dFinclude <Geometry.h> 


void main() 
{ 
TGRect unUsedRect(0, 1, 2, 4); 
unUsedRect.PrintObject(); // Print coordinates 
} 


Rebuild the application. 
Makeit SimpleSample. 
The build log looks similar to this: 


i 

## Making "SimpleSample" for "/home/EeeDee/SimpleSample"... 

/#f make -f SimpleSample.Make SimpleSample 

i 

## Compile hello.C to produce hello.o 

MakeSharedApp -L. -L/usr/lib/dce -o SimpleSample hello.o /home/EeeDee/work/Expo 
rts/RuntimeLib.e /home/EeeDee/work/Exports/O0pixLib.e /home/EeeDee/work/Exports/T 
oolboxLib.e /home/EeeDee/work/Exports/TimeLib.e /home/EeeDee/work/Exports/TestFr 
ameworkLib.e /home/EeeDee/work/Exports/HighLevelAlbert.e /home/EeeDee/work/Expo 
rts/LowLevelAlbert.e /home/EeeDee/work/Exports/AlbertPixelBuffers.e 


Running the new SimpleSample should print these results: 


4SimpleSample 

OPIX compile timestamp = Jan 22 1994, 08:25:22 

TGRect (top = 1.000000, left = 0.000000, bottom = 4.000000, right = 2.000000) 
% 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT INTERNAL TOOLS 


52 CHAPTER 4 ‘THE BUILD ENVIRONMENT 
REAL LIFE EXAMPLES 


A clean build To ensure a successful build, delete all the object files before you build a project 
(or project hierarchy). Clean instructs Makeit to delete the object files before 
building the project. | 


Makeit Clean Complete 


POOL ALPE M, PEPE PL PEP OLL LPL IML GSO EEP OPED LILI RL LEI IIRL EOP ELI REED EPIL II LE ILD IL ELPA LILIEOD OLED EOL OPE EL OLED PDIP IP LL OLE LLAIDI LOL ML 


A not-so-simple TuffyData is an application with several dependency files. This makefile 
makefile description for TuffyData (TuffyData.PinkMake) is typical of a Taligent 
application. 


// $Revision: 1.1 $ 
// Copyright (c) 1994 Taligent, Inc. All Rights Reserved. 


Used by all compile —--- compi leoption: -D__DEBUG__ -DUSE_FILE_SEGS 
commands. | 
start { 
Copy these make TestHeaderDir=../../AES/UE/Local Includes 
commands into the ’ 
Paces LocalIncludes :: 
beginning of the 
Adie test -d $(TestHeaderDir) || mkdir $(TestHeaderDir) 
generated makefile. } 
Directory of headers —---—- localheaderdir: $(TestHeaderDir) 
to export. _ 
library CellModelLib { 
publicheaders: 
CellModel.h 
CellModelView.h 
D 
ReSOHEIES ae CellSelectionInteractor.h 
makefile commands for source: 
creating the runtime CellModel.C 
library. CellModelView.C 


| 

| 

| 

| 

| 

i 

| CellSelections.C 

| Cel1lModelCommands.C 

| CellSelectionInteractor.C 
| link: 

GraphicDocumentLib 

| StandardDocumentLib 

| NewGraphicApplicationLib 
| BDFTestLib 
CompoundDocumentLib 
BasicDocumentLib 

| NewControlsLib 
ConstructorArchiveLib 

| AlbertScreens 

| {UniversalLinkList} 


Seowan 
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binary CreatelTuffyData { 
source: 


Create make CreateTuffyData.C 
dependencies for ee earns 
e11ModelLi 
1 
ie iad ae oul StandardDocumentLib 
single mxCCuIane ie GraphicDocumentLib 
these sources linked in. NewGraphicApplicationLib 
BDFTestLib 


CompoundDocumentLib 
BasicDocumentLib 
NewControlsLib 
ConstructorArchiveLib 
AlbertScreens 
{UniversalLinkList} 


wedicetitistidteccecctecterstietceretenbleladaebirarenrrrcee a 


A simple *.PinkMake §=How do you determine which link files you need to specify in your *.PinkMake 
file? If you don’t specify any link files, CreateMake links all library files. As you can 
imagine, this is not economical. Currently, the only way to determine which link 
files to include is by trial and error, and with a little help from FindSymbols. 


Consider this makefile description called JustAView.PinkMake. JustAView builds a 
shared library and an application binary. To link all library files, create 
JustAView. PinkMake like this: 


Shared library —-————~__ library JustAViewLib { 
| source: 
! MyView.C 
3 
Main application binary ~~~ i binary JustAView { 
| source: 
Main.C 
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To determine which library files to link, include link: targets and specify 
{SimpleLinkList} as the tag in each list. {SimpleLinkList} is a variable specifying 
a minimal set of libraries that most applications require: 
library JustAViewLib { 
source: 
MyView.C 
Add link targets ——--——--------|_ link: | 
{SimpleLinkList} // Minimal set 
3 
binary JustAView { 
source: 
Main.C 
Add link targets ————-—-—-_ link: 
| JustAViewLib // The JustAView library created above 
| {SimpleLinkList} // Minimal set 
ae. 


When you build the JustAView project, Makeit will list errors for undefined 
symbols encountered when MakeSharedLib executes. In the messages, look for 
errors like these below the MakeSharedLib command line: 


... MakeSharedLib -o JustAViewLib ... : 

Td: 0711-317 ERROR: Undefined symbol: .TGArea::~TGArea( ) 

ld: 0711-317 ERROR: Undefined symbol: .TRGBColor::~TRGBColor() 
1d: 0711-317 ERROR: Undefined symbol: .TGRect::~TGRect( ) 

1d: 0711-317 ERROR: Undefined symbol: __vttl2TContentView 


To find the library files in which these symbols are defined, use FindSymbols. 
(The first time you run FindSymbols, it parses all library files and builds a 


database file so that subsequent lookups execute quickly.) To perform a lookup, 


Link tag to add 


run FindSymbols and specify the symbol exactly as it appears in the error listing. 
The symbol name must be enclosed within apostrophes (single quotes). 


FindSymbols '.TGArea::~TGArea()' 


Which produces a listing like this: 


TGArea: :~TGArea(): 
HighLevelAlbert 


This is the unique set of libraries identified: 
HighLevelAlbert 


This listing indicates that the symbol is in HighLevelAlbert. Add thatname as the 
tag in the library’s link: target. To look for multiple symbols at once, include 
each as a separate argument on the FindSymbols command line:. 


FindSymbols '.TRGBColor::~TRGBColor()' '.TGRect::~TGRect()" ' _vttl2TContentView' 
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Which produces this listing: 


TRGBColor::~TRGBColor(): 
LowLevelAlbert 

TGRect: :~TGRect(): 
CommonAlbert 
HighLevelAlbert 
__vttl2TContentView: 
NewGraphicApplicationLib 


This is the unique set of libraries identified: 
CommonAl bert 
HighLevelAlbert 
LowLevelAlbert 
NewGraphicApplicationLib 


Notice that TGRect: :~TGRect(): appears in CommonAlbert and HighLevelAlbert. 
When you get multiple libraries, you probably need to include only one. Try one 
and if you still get errors for the symbol, try the other. In a worst case, include 
both. This example only needed HighLevelA1 bert. 


library JustAViewLib { 
source: 
MyView.C 


link: 


Add link targets ----------------------" HighLevelAlbert // Add 


PRELIMINARY 


LowLevelAlbert // Add 
NewGraphicApplicationLib // Add 
{SimpleLinkList} 

} 


binary JustAView { 
source: 
Main.C 


link: 


{SimpleLinkList} 
} 
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Even if you lookup every symbol in the list, it probably won’t be enough to build 
completely, because the libraries might also require other libraries. When you 
build JustAView again, you get these errors: 


...- MakeSharedLib ... : 
- |d: 0711-317 ERROR: Undefined symbol: __vtt5TView 
Td: 0711-317 ERROR: Undefined symbol: .TView::GetClassMetaInformation() 
Td: 0711-317 ERROR: Undefined symbol: .TEventSenderSurrogate: :GetClassMetaInformation() 


Repeat the lookup and *.PinkMake modification until MakeSharedLib doesn’t — 
return an error. 


Once your build gets past MakeSharedLib without error, you will probably find 
MakeSharedApp producing similar errors: 


- MakeSharedLib ... 
. MakeSharedApp ... | 
ld: 0711-317 ERROR: Undefined symbol: TView::virtual-fn-table-ptr-table 
Td: 0711-317 ERROR: Undefined symbol: .TView::GetClassMetaInformation( ) 
Td: 0711-317 ERROR: Undefined symbol: .TEventSenderSurrogate: :GetClassMetaInformation() 
1d: 0711-317 ERROR: Undefined symbol: .TInputDevice: :GetClassMetaInformation( ) 
ld: 0711-317 ERROR: Undefined symbol: .TViewRoot: :~TViewRoot() 
1d: 0711-317 ERROR: Undefined symbol: .TViewRoot::TViewRoot(TRequestProcessor*) 
ld: 0711-317 ERROR: Undefined symbol: .TViewRoot: :AdoptChild(TView*) 


Use FindSymbo1s again, but this time, add the 1ink: tags to the binary target. 


library JustAViewLib { 


source: 
MyView.C 
link: 
ViewSystemLib 
InputLib 
HighLevelAlbert 
LowLevelAlbert 
NewGraphicApplicationLib 
{SimpleLinkList} 
} 
binary JustAView { 
source: 
Main.C 
link: 
Add link targets ——----------------—, ViewSystemLib 
| Imeeti 
JustAViewLib 
{SimpleLinkList} 
i 


Repeat the process until Makeit completes the build. 
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Often you need to build the entire system to ensure that your application pieces 
are functioning together. You can install a copy of the latest build to your file 
system with InterimInstal1 (layer) or NativeInstal1 (native). These scripts copy 
a set of headers, libraries, and shared libraries to your local system. Once you 
install a build and its associated files, you can modify, debug, or build on top of 
that particular build. 


For more information about InterimInstal1, see “InterimInstall” on page 64, 
and for NativeInstal1, see “NativeInstall” on page 7o. To install a system build, 
follow the instructions provided in “Install the build” on page 5 or “Install the 
Native TalOS build” on page 7. 
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PRELIMINARY 


CHAPTER 5 


‘TALIGENT BUILD TOOLS 


The Taligent build tools include tools and scripts that you run from the 
command line, and tools and scripts that those tools call. While this chapter 
documents how to run all of the Taligent build tools, there are some tools that 


you should avoid and are so noted. In addition , some tools require you to log on — 


with super uSer access. 
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CREATEMAKE 


re ee 


Installation 


syntax 


Arguments 


Usage 


Makefile format 


CreateMake reads a file Project.PinkMake and creates a UNIX makefile for 
building the project. CreateMake writes the makefile to stdout; by convention, 
you should redirect the output to Project.Make. 


CreateMake is located in /usr/taligent/bin and requires no installation. Make 
sure this directory is in your command search path. 


CreateMake [sourcefile] [-fast] [-D define]... [-target target] [-I includePath]... 


“—D define 
-fast 


—target target 


—| includePath 
—noum 


outputfile 


sourcefile 


“Vers 


[-noum] [-vers] > outputfile 


Include the specified definition during processing. 


Preprocess the source files and create a single .c that#includes the source 
files to build each target. this results in faster builds, but is notto be used for 
final builds. | 


Generate a makefile for a specific target. Currently used only by Taligent 
Operating System and the fargetis intel. Use Universal .Make. Intel 
instead of Universal .Make. 


Add the path to the ##include directory search-list. 
Generate a makefile that does not rely on Universal.Make for processing. 


The file containing the new makefile. If you omit outputfile, output goes to 
stdout. 


The input file to process is usually a *.PinkMake filename. If you omit sourcefile, 
CreateMake assumes the current directory name is the project. For example, if 
the current directory is /TestLib, the sourcefile is TestLib.PinkMake. 


Echo the current version and copyright information to stderr. This is the same 
header that appears at the top of created makefiles. If you use this option with no 
other parameters, the information echoes and CreateMake exits. Otherwise, the 
information echoes and processing continues. 


You do not usually call CreateMake directly; instead, you should use Makeit to 
automatically invoke it (see “Makeit” on page 66). Makeit executes CreateMake if 
the makefile is out-of-date or missing. 


See Chapter 4, “Makefiles,” for a formal definition and syntax for the makefile 


descriptions. 


CreateMake generates a standard AIX makefile whose content depends on the 
targets in sourcefile. Each makefile supports the standard Taligent build steps 
(Includes, Objects, Exports, and Binaries). 
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Examples 


syntax 


Arguments 


Usage 
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Simple projects require simple make commands. For example, to create a 
makefile named Sample.Make which builds a target from the C source files in the 
working directory: 


CreateMake Sample.PinkMake > Sample.Make 
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FindSymbols reports the shared libraries that contain the specified symbols. 


FindSymbols [ 'symbol" ... ] 


symbol The mangled, demangled, or mixed-form symbol to locate. The argument 
must be enclosed in single quotes (’). 


Use FindSymbols when MakeSharedLib or MakeSharedApp report unresolved 
symbols, and you want to know which libraries you should add to the link list in 
your *.PinkMake file. 


The first time you run FindSymbols, it builds a cache file: $TaligentExport/ 
_A11Symbol1s. Subsequent runs consult that cache file. To rebuild or update the 
file, delete it and rerun FindSymbols. When you install a new build, 
InterimInstall1 should delete the cache. 


NOTE If FindSymbols can’t locate a symbol that you are certain exists, the 
symbol is probably an inline. There is no way to find inlines, because they are 
compiled into client code, as opposed to being compiled into and exported from 
a library for use by clients. 


Because the implementation of an inline must be compiled with the header, you 
should be able to find the inline declaration if you do enough searching: it will 
either be hidden down near the bottom of the header, or in another file that is 
an #include in the header (typically similar to “XXXXImplementation.[ih]”). 


A compiler is free to not inline an inline if doing so would generate worse code. 
This means that some symbols declared inline might not actually be inlined, and 
so can wind up compiled into and exported from a library which—if not in the 
* ,PinkMake’s link list—would lead to an unresolved symbol error. 
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FINDSYMBOLS 


Example 


Link tag to add to 
your *.PinkMake 


You will typically use FindSymbo1s to locate the library that caused an “Undefined 
symbol” error when your build fails. For example, Makeit might list errors for 
undefined symbols encountered when MakeSharedLib executes. In the messages, 
look for errors like these below the MakeSharedLib command line: 


... MakeSharedLib -o JustAViewLib ... 

Td: 0711-317 ERROR: Undefined symbol: .TGArea::~TGArea( ) 

1d: 0711-317 ERROR: Undefined symbol: .TRGBColor: :~TRGBColor() 
1d: 0711-317 ERROR: Undefined symbol: .TGRect::~TGRect() 

Id: 0711-317 ERROR: Undefined symbol: __vttl2TContentView 


To find the library files in which these symbols are defined, run FindSymbols and 
specify the symbol exactly as it appears in the error listing. The symbol name 
must be enclosed within apostrophes (single quotes). 


FindSymbols ‘.TGArea::~TGArea()' 


Which produces a listing like this: 


TGArea::~TGArea(): 
HighLevelAlbert 


This is the unique set of libraries identified: 
HighLevelAlbert 


This listing indicates that the symbol is in HighLevelAlbert. 


To look for multiple symbols at once, include each as a separate argument on the 
FindSymbols command line: 


FindSymbols ‘.TRGBColor::~TRGBColor()" '.TGRect::~TGRect()' ‘'__vtt1l2TContentView' 


Which produces this listing: 


TRGBColor: :~TRGBColor(): 
LowLevelAlbert 

TGRect: :~TGRect(): 
CommonA1 bert 
HighLevelAlbert 
__vttl2TContentView: 
NewGraphicApplicationLib 


This is the unique set of libraries identified: 
CommonAl bert 
HighLevelAlbert 
LowLevelAlbert 
NewGraphicApplicationLib 


Notice that TGRect: :~TGRect(): appears in CommonAlbert and HighLevelAlbert. 
When you get multiple libraries, you probably need to include only one. Try one 
and if you still get errors for the symbol, try the other. In a worst case, include 
both. This example only needed HighLevelAlbert. 
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It’s also possible to find symbols before using Makeit. To do so, you must take a 
symbol from C++ code and put it into the canonical form used by the linker. This 
isn’t easy. Here are some rules for functions that work 80-90% of the time: 


Remove the return value. 
Preface the function with the ClassName followed by “::”. 
Remove all argument names. 


ZI Remove all whitespace, except: 


® There should be exactly one blank after all const keywords inside a 
function’s argument-parenthesis. 


@® There should be exactly one blank after a function’s closing ‘)’ and 
before a const keyword. 


For example: 


class TSomeClass { 
int SomeFunc( const TSomeType* someArg, 
TOtherType& otherArg ) const; 
} 


becomes: 

TSomeClass::SomeFunc(const TSomelype*,TOtherType&) const 

Complications creep in when one or more of the types involved are #define’s or 
typedef’s. In such cases, it’s better to choose a different function. 


With practice, you can get good at this technique, and can even find other kinds 
of symbols (enum’s, for example). ‘This may seem like a lot of work, but at least you 
don’t have to keep running the linker. | 


This technique is best when you have a program that is already compiled and 
working, and you add some new functionality to it. Then you have a good idea of 
what new symbols you've introduced, and what symbols to search for. 
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INTERIMINSTALL 


InterimInstal1 is a script that automates the installation process for the layer; to 
install native, use NativeInstall. InterimInstal11 installs the most recent build by 
default, or can install a specific build. 


syntax InterimInstall] [ -1 | [ -S | -D | -0 ] [-b] [-r releaseName ] ] 
ieanaene - ee ee a ie ate acento ae | 
-b Blast the release currently installed on your system. Most of the files in the 


Taligent directories are not writable, but must be removed before a new build can 
be installed over them. This option removes the pertinent directories under 
$TaligentRoot, but does not modify $TaligentRoot/Taligent except to remove 


universal.Make. 
—] List the builds currently available for downloading. You cannot use this with any 
| other option. 
—0 Install the optimized release. 


-r releaseName A specific release to install. lf you do not specify a release, InterimInstal1 
downloads the current build. 


-S Install the stripped release. © 


Example To install MS-0.07 debug and remove the existing release: 


InterimInstall -D -b -r MS-0.07 


Ke blas + more_ 
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| IPCPURGE 


IPCPurge purges global shared interprocess resources (such as global semaphores 
and shared segments) from memory. Usually IPCPurge is called from mop, which 
is called from StopPink. 


IPCPurge 


CAUTION IPCPurge causes running Taligent applications to end abnormally. 


IPCPurge is used within the layer only; the native environment doesn’t have an 
equivalent function. 


MakeExportList generates an .e file from an .o file (which is a combination of one 
or more x1C compiled .C files). Clients of a shared library link with the -e file, 
which is a text list of all the symbols that the shared library provides. 


CreateMake executes this command for you when you are building libraries. You 
should not have to run it independently. 


MakeExportList -1 SharedLib MyLib.o > SharedLib.e 
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MAKEIT 
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MAKEIT 


Installation 


Syntax 


Arguments 


Makeit is a wrapper (a front end) to make. Makeit simplifies the builds and 


provides consistency. It has the ability to traverse project hierarchies and convert 
makefile descriptions to real makefiles (by calling CreateMake). 


Makelt is located in /usr/taligent/bin and requires no installation. Make sure 
this directory is in your command search path if MakeIt fails to run. 


Makeit has only a few options; however, it passes all other options onto make. So in 
effect, Makeit has the same options as make, plus its own options. 


Makeit Loptions] [Targets] 


Makeit passes any unrecognized arguments on to make. 


—C 


VAR=value 


—vers 


Targets 


Makeit Makefiles 


subprojects from the bottom up, executing targets at every project it finds ina 
subproject{} block. 


Do not rebuild a make file, even if it is out of date. | 
Do not stop when errors are encountered. This is passed on to make as -i. 
CreateMake option; Makeit passes this option to CreateMake. 


Force all makefiles to be rebuilt on the fly by calling CreateMake even if files 
are up-to-date. 


Traverse the project tree, but do not build anything. 


Assign value to the variable named VAR. Makeit passes this expression to 
make to alter makefile variable usage. 


Echo the current version and copyright information to stderr. 


The targets to build. If you omit this option, Makeit builds each target in the 
current project (Includes, Objects, Exports, and Binaries) and the necessary 
dependencies. You can also specify complete to build the four targets. 


Makefiles is a special targetthat generates a new makefile, but does not build 
anything. Use this for debugging. 
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Usage 


Passing options to make 


Creating makefiles 
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Go through each build process target (Includes, Objects, Exports, and pInaries) 
and build the necessary dependencies. 


Makeit 
To build DemoApp, and its subprojects: 
Makeit DemoApp 


A common mistake is to tell Makeit to build one target (like the previous 
example), and not realize that it will execute make DemoApp on all subprojects— 
many of which do not have a target DemoApp. To prevent Makeit from building 
subprojects: 


Makeit -c DemoApp 


To require Makeit to execute only the Includes and Exports targets in each 
directory. 


Makeit Includes Exports 


Makeit accepts (and passes) all options to make. You can use this feature to pass 
options to make. For example if you want make to continue building even if an 
error occurs (-i option for make): 


Makeit -i Objects 


This works similarly for any make option. Makeit is smart enough to pass on any 
arguments for options too. For example, you can override variables in makefiles 
as you can with make. To override the COPTS (compiler options) variable in the 
makefile: 


Makeit COPTS=-g Binaries 


Makeit can build makefiles on the fly. Makeit rebuilds a makefile if: 
# the *.Make file does not exist 
« the *.PinkMake file is newer than the *.Make file 
# you specify -M to override the automatic makefile generation 


Makeit uses CreateMake to translate the makefile descriptions (*.PinkMake) to 
makefiles (*.Make). CreateMake is akin to the CreatePinkMakefile tool used by 
the native system in MPW. For more information see “CreateMake” on page 60. 
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MAKESHAREDAPP _ 


Universal.Make 


Other global targets 


Capitalization 
is optional 


To prevent duplication in each makefile, and to allow for more flexibility, Makeit 
includes Universal.Make in every makefile (*.Make). Universal.Make contains 
global targets and rules, such as Includes, Objects, Exports, and Binaries. 


(NOTE Be sure to follow the installation procedures in “Setting up for 
Taligent Application Environment” on page 3 and check out a correct version of 
Universal.Make to your $TaligentRoot/Taligent. Do this before you attempt to 
build anything with Makeit. 


In addition to the global targets previously mentioned, other global targets are 
also useful because they are applied only to the projects in the build and not to 
every directory in the hierarchy. For example you might have an entire 
subsystem, that exists, has been checked into SCM, but is not part of the build. 
These targets will not be applied to those projects: 


Global Target Task 


Clean Removes all .o and .e files, and libraries that were built. 
Complete Expands into the four standard targets: Includes, Objects, Exports, 
and Binaries. 


Makefiles Allows you to traverse the directory and rebuild makefiles as needed. 
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Usage 


Example 


MakeSharedApp builds executable applications or programs (it is a wrapper for an 
x1C command with special options). MakeSharedApp is a layer application; the 
native environment doesn’t have an equivalent function because | 
Universal .Make. Intel automatically calls Plink to handle this. 


CreateMake generates this command for you when you build binaries or 
programs (applications). You should not need to run it independently. 


~The following example builds the MyApp executable, and specifies two search 


paths -L. (current directory) -L/usr/1ib/dce which will be searched in the order 
specified to load shared libraries SharedLib1] and SharedLib2. If SharedLibl and 
SharedLib2 are not in these directories, the AIX runtime searches in the path 
specified by LIBPATH. 


MakeSharedApp -o MyApp AppMain.o SharedLibl.e SharedLib2.e -L. -L/usr/lib/dce 
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syntax 


Arguments 


Usage 


RPP P taht, 
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OCONEE EO 


MakeSharedLib is a wrapper to the AIX makeC++SharedLib script, which combines 
.o and .a files into a single shared library, and uses .e files to resolve external 
symbols located in other shared libraries. MakeSharedLib is a layer application; 
the native environment doesn’t have an equivalent function because 

Universal .Make.Intel automatically calls Pl ink to handle this. 


CreateMake generates this command for you when you are building libraries. You 
should not have to run it independently. 


To create a shared library named SharedLib1 that uses the code in MyLzb.o, and 
resolves external symbols by looking in SharedLib2.e: 


MakeSharedLib -p 6000 -o SharedLibl MyLib.o SharedLib2.e 
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MakeSOL registers export-file libraries for Taligent Application Environment. 


MakeSOL [-c | -t | -e pattern | -i pattern | -I files | -E files] [-a file] [-v] 


-afile ~~‘ Anadditional file to register. 


—C Detects linking against .e files that don’t have corresponding library files. 
—e pattern Excludes files matching the pattern. 

—E file Excludes the files listed. 

—| pattern Includes files matching the pattern. 

—I file Includes the files listed. 

—t Includes the test libraries. By default, they aren't included. 

-V Lists—to stdout—status messages and the files registered. If you omit this 


option, only warning and error messages appear. 


Use MakeSOL to add new libraries; ones that aren’t already in the build. 
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MOP 
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syntax 


syntax 


Arguments 


Example 


mop is a wrapper for IPCPurge. In addition to calling IPCPurge, it removes 
temporary files created by the AIX implementation of ScreamPlus. You can run 


Mop independently, but it is best to let StartPink or StopPink call it. 


mop 


mop is used within the layer only; the native environment doesn’t have an 
equivalent function. 


NativeInstal1 is a script that automates the installation process. NativeInstal1 


installs the most recent build by default, or can install a specific build. 


NativeInstall [ -1 | [ -D] [-b] [-r releaseName ]_ ] 


-b Blast the release currently installed on your system. Most of the files in the 
Taligent directories aren’t writable, but must be removed before a new build can 
be installed over them. This option removes the pertinent directories under 
$TaligentRoot, but does not modify $TaligentRoot/Taligent except to remove 
Universal .Make. | 


—] List the builds currently available for downloading. You cannot use this with any 
other option. 


-r releaseName A specific release to install. If you do not specify a release, NativeInstal1 
downloads the current build. 


-T Do not install tools into $TaligentRoot/ToolsDir. Instead, let NativeInstal1 
install tools that are synchronized with your source code. 


To install N10.1 and remove the existing release: 


NativelInstall -b -r N10.1 
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syntax 


Arguments 


Usage 
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rp loads and runs a Taligent Operating System program that was built with 
shared libraries; for programs that don’t use shared libraries, use runpink 
instead. 


rp [ +a args ] programName 


+a args Pass the specified arguments to the program. 
programName _ the shared-libraries built Taligent Operating System program. 


NOTE rp is only available within Taligent Operating System. For layer 
programs, use StartPink. 


Before invoking rp, you need to start up the Shared Library server. To do this: 
rp _libserver & 

Then, start up your program with: 

rp MyProgram 
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RUNDOCUMENT 
Rualioctisnrs 
RunDocument creates, opens, or deletes a document that accesses a shared library 
already running in the Taligent Application Environment workspace. 
Syntax | RunDocument [-c Class SharedLib | -o [-s Mode ] [ -p Way ] | -d ] [ DocumentName ] 
Arguments “~¢ Class SharedLib Creates a new document from the TAbstractDocumentStationery subclass 
Class, which is defined in the shared library SharedLib. Can be combined 
with -o to open and create at the same time. 
lf DocumentName already exists, RunDocument appends an integer <n> 
to the name, where <n>is 2 or greater such that the name is unique. 
—d Deletes DocumentName. | 
—0 | Opens DocumentName. Can be combined with -c to open and create at 
the same time. 
—p Way Specifies the task in which to open the document. Way can be: 
0 = open in same task (default.). 
1 = open in a new task. | 
-§ Mode Specifies the mode in which to open the document. Mode can be: 
0 = examine store (default.). 
1 = assume this is a basic document. 
2 = assume this is a compound document. 
DocumentName The document created, opened, or deleted. If you omit DocumentName, 
use “Untitled” as the default. 
Usage RunDocument prints, to stdout, one of these status codes: 


0 
= 
2 
3 
4 
5 
6 


No error. 

Syntax error in arguments. 
Stationery class not found. 
Document not found. 
Could not delete document. 
Could not open document. 


Could not determine document store type. 


'¢ NOTE In SDKI, if you are running multiple instances of RunDocument, two 
of them can pick up the same document name. One will successfully create that 
document, but the other will get an exception that causes a SIGIOT. Be sure to use 
a unique name for each instance. 
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RUNPINK 
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runpink loads and runs a Taligent Operating System program that don’t use 
shared libraries; for programs that use shared libraries, use rp instead. 


syntax runpink [ +f ] [ +a args ] programName 


Arguments +a args Pass the specified arguments to the program. 
+f Do not invoke the built-in runpink debugger. Just execute the program. 
programName The Taligent Operating System program. ; 


¢ NOTE rp is only available within Taligent Operating System. For layer 
programs, use StartPink. 


Example Start a program, and pass two arguments: | 


rp ta “couch" MyProgram 
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SHAREDLIBCACHE 


SharedLibCache builds a cache of symbol addresses at the end of shared libraries 
for fast subroutine lookup during TStream::Flatten and TStream::Resurrect. 
MakeSharedLib uses SharedLibCache to cache the default constructors of 
MCollectibles for resurrection. 


syntax SharedLibCache [-d sharedLib] [-da sharedLib] [-r sharedLib] 
Arguments —d sharedL ib Create cache of symbols req uired for flatten/resurrect. 
—da sharedLib Create cache of all formal symbols (rarely used). 
—r sharedLib Display the contents of an existing cache. 
Usage Running strip on a shared library destroys its cache; rerun SharedLibCache to 
rebuild the cache. | 


NOTE SharedLibCache is also called s1cache. 


SharedLibCache is used within the layer only; the native environment doesn’t 
have an equivalent function. 
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SLIBCLEAN 


SLIBCLEAN 


syntax 


Usage 


syntax 


Arguments 


s1ibclean cleans up global semaphores and global variable space. (Run by 
StopPink.) 


slibclean 


Run s1ibclean between running different versions of Taligent Application 
Environment. The file /etc/s1ibclean should be owned by root and swid. 


$1ibclean is used within the layer only; the native environment doesn’t have an 
equivalent function. 


SmartCopy is a cp imitator that solves one specific problem: during the Includes 
phase of the build, when header files are copied to $TaligentIncludes, if a file 
exists in $TaligentIncludes, and it is write protected, cp fails but SmartCopy does 
not. SmartCopy performs one other important task: it preserves the modification 
date to prevent unnecessary rebuilds. SmartCopy copies a file unless the target file 
has exactly the same date and time, and the same size as the source file. This 
should save you the time of copying the same file over itself, and is more certain 
to copy a file that is truly different. 


SmartCopy sourceFile.. destFile 


destfile  ++-~—«‘Theddestination of the filebeingcopied. = 


sourceFile The file(s) to copy. 
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CO a 


STARTPINK 


oyntax 


Arguments 


Usage 


syntax 


Usage 
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STARTPINK 


StartPink starts the Taligent AIX reference layer and several servers. The 
remaining servers are started when they are needed (when you launch a Taligent 
Application). 


StartPink [-a applicationName ] [-q] [-n [-s] ] 


—a applicationName Load and run the named application. 


—n Use merged servers. If you omit this option, StartPink uses non- 
merged servers. 


Merged servers give you a smaller memory footprint, faster start-up, 
and better interactive performance, but less stability. 


-q ; Do not load shared libraries. 


—S otart merged servers as a one. If you omit this option, the merged 
servers start in three groups. -s has no effect if you omit -n. 


When the StartPink script finishes, it displays a message, similar to this: 


Welcome to the Taligent AIX Layer 
Based from v1.0d29 


Copyright (C) 1993, 1994 Taligent, Inc. 
All rights reserved. 


StartPink is used within the layer only; the native environment doesn’t have an 
equivalent function. 
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StopPink safely takes down the Taligent AIX layer. StopPink seeks out and kills 
the servers that StartPink started. It also runs mop and s1ibclean, see “mop” on 


page 70. 
StopPink 


StopPink only kills system servers and applications, not applications that are 
running. Always quit your applications before running StopPink. 


StopPink is used within the layer only; the native environment doesn’t have an 
equivalent function. 
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PPI! 


PRELIMINARY 


PRELIMINARY 


CHAPTER 6 


CREATEMAKE 


CreateMake generates *.Make files for use with the Taligent build system. This 
chapter describes each of the targets, tags, and options that are available for 
input into CreateMake. For information about using CreateMake, see “Makefiles” 


on page 43. 


NOTE When building for Taligent Application Environment, references to 
compile and link methods are referring to the IBM x1C compiler and linker. 
When building for Taligent Operating System, references to compile and link 
methods are referring to the Comptech-on-AIX C++ compiler and the Plink-on- 
AIX linker. 


CreateMake is a Taligent AIX tool that evolved from a similar Macintosh tool 
called CreatePinkMakeFile. CreateMake is faster and can perform more 
operations than its predecessor. Also, CreateMake does not require external tools, 
such as the old MakeMake. CreateMake accepts most of its predecessor’s keywords; 
however, these keywords are not implemented: 


asmoption, dependson, exportclient, exportsample, ISR, makemakeoption, 
opusbugtemplate, otherheaderdir, othersourcedir, plinkclientoption, 
plinklibraryoption, plinkoption, prelude, programdata, and resident. 
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APPLICATION 


Keyword categories 


Path names 
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APPLICATION 


Syntax 


Argument 


Example 


BINARIESSUBFOLDERDIR 


There are four categories of CreateMake keywords: 


Targets generate dependencies for a specific output target. All targets contain at 
least one source file declaration with which to build the target. Targets can contain 
various tags, but never other targets. 


Tags are target specific identifiers for components within that target. Use tags 
within targets to specify, for example, source and header files. 


Variables are keywords used within the generated makefile to control various 
options. | 


Customs are keywords that allow custom control over the generated makefile. 
start and end are examples of custom keywords. 


If a file name contains a slash or starts with a variable, such as $(...), CreateMake 
assumes that you have specified a complete file name. To interpret the name 
literally, enclose the name in single quotes; that is, CreateMake will not prepend a 
directory or append a suffix. 


This is an obsolete target; use binary instead. 
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This variable overrides the default destination for binaries built by the makefile 


that CreateMake generates. The default directory is $TaligentBinaries. 


binariessubfolderdir: directoryPath 


directoryPath The path location to copy the built binaries to. This can be an explicit path ora 
shell variable. 


binariessubfolderdir: $(TaligentRoot)/MyBinaries: 
library MyLibrary { 
source: 

Library.c 


‘@ NOTE For Release A, this keyword is a synonym for subfolderdir, the 
directory identifier used by export{subfolder:}. In later releases, this variable 
will work as described. 
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BINARY 


syntax 


Argument 


Example 


PRELIMINARY 


iviecdrProsop ep irored 
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BINARY 
This target creates dependencies for a Taligent application, generates all make 
dependencies for creating a Taligent application, and builds an executable/ © 
library pair with all sources in the library. 
binary name { 
} 
name The name of the target, and the name used as a prefix for makefile variables, 


include lists, and dependencies. 


An unsupported version of this target is available with the ubinary keyword. 
Unsupported targets are similar to supported targets, except that they are not 
built in the normal build process (Makeit) and require the desired target to be 
explicitly stated for the build to occur. 


Produce a makefile for compiling the three source files, link them together with 
standard Taligent libraries, and create a main program binary and a shared 
library containing most of the code. Both of which contain the name “MyApp”: 


binary "MyApp"™ { 


source: 
main.c 
TMyApp.c 
TMyView.c 
} 


NOTE programis asynonym for binary. 
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BUILD 


BUILD 


syntax 


Example 


I a em a eR i ae Eee 


Pte 


This tag is for specifying build rules that control a specific target, from within 
that target. The lines following build must have the correct indentation; they are 
copied directly into the generated makefile. 


build: 
"$(ObjDir)/Sample.op" : Sample.txt 
$(BuildHelp) Sample.txt -o target 


libraryMySample { 

source: 
SampleStartup.c 
SampleIndex.c 


build: 
$(ObjDir)/Sample.op” : Sample.txt 
$(BuildHelp) Sample.txt -o target 


link: 
Sample.op 


COMPILEOPTION 


syntax 


Argument 


Examples 


This variable sets a local variable in the makefile that is used in any compile 
commands executed. | 
compileoption: -d option 


option Any option you want to pass on all compile command-lines generated. 


Create a parent object that requires one source file. Pass (WWHATEVER_ to the 
compiler when that source file is compiled: 


compileoption: -d _WHATEVER_ . 
parentobjects MyObject{ 


source: 
HandleObject.c 


?NOTE  cplusoption is asynonym for compileoption that will soon be 
eliminated. Change all occurrences of cplusoption to compileoption. 
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DEVELOPMENTOBJECT 


syntax 


Argument 


Examples 


PTET eT eeS 


END 


syntax 


Argument 


Example 


PRELIMINARY 


This target combines the specified source files into a library object, and copies 
the result object file to $TaligentDevelopment. 


developmentobject name { 


developmentobject "SampleObject” { 


source: 
SampleInput.c 
SampleQutput.c 
} 


NOTE developmentobject is currently treated the same as object. 
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This custom target allows you to supply a block of make commands to copy into 
the end of the generated makefile. 


end { 
makeCommands 


makeCommands _ Any valid makefile syntax. CreateMake places this block directly into the 
generated makefile; pay careful attention to indentations and syntax. 


end { 
Foo : Bar 
dt build rules 
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EXPORT 


EXPORT 


syntax 


Argument 


Example 


Meeeteeeededcedeertiadecceraccricrccteeadigtrereetrecidtcedececess 


A variable that specifies that files in your project be exported to various Taligent 


directories. 


export { , 
exportTags 


exportlags. Control which files are exported. Valid tags are: binary, client, 
subfolder, program, data, script, server, library, testlibrary, 
testdata, and script. 


The example shows the destination of each of the supported tags. 


export { 
binary: 

SampleExportBinary 
client: 

SampleExportClient 
subfolder: 

Samp leExportSubfolder 
program: 

Samp leExportProgram 
data: 

SampleExportData 
script: 

SampleExportsScript 
server: 

SampleExportServer 
library: 

Samp leExportExportLibrary 
testlibrary: | 

SampleExportTestLibrary 


TestSharedLibaries: 


testdata: 
SampleExportTestData 
itestscript: 
SampleExportTestScript 
} 3 
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// 


// 


// 


// 


// 


// 


// 


// 


// 


// 


to 


to 


to 


to 


to 


to 


to 


to 


to 


to 


$(TaligentBinaries) 
$(TaligentLibraries) 
$(TaligentBinaries)/subfolder 


$(TaligentBinaries) 


$(TaligentSamples) 
$(OPD)/Servers: 
$(OPD)/SharedLibaries: 
$(OPD)/SharedLibraries: 
$(TaligentTests)TestData: 


$(TaligentTests)TestScripts: 
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HEADER 


syntax 


Argument 


Examples 


HEADERDIR 


syntax 


Example 
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Header files listed after this tag specify an explicit dependency for the target. 


header: 
headerFiles 


library MyLibrary { 
source: 


LibraryInit.c 
LibraryI0.c 


header: 
$(CustomHeaders)Library.h 


"NOTE In Release A, header acts like publicheader in that the specified files 
are exported to $TaligentIncludes. header will act as described in future releases. 


POPP LOB OD PDD. 
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This tag specifies an alternate directory in which header files are stored. By 
default, CreateMake generates makefiles with references to headers in the same 
directory as the makefile. CreateMake passes the reference to the compiler. 


headerdir: 


headerdir: ../MyHeaders: 
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HEAPSIZE 
HEAPSIZE 
This target controls the allocated heap size of a built Taligent application. 
Syntax heapsize: heapSizex 
Argument heapSize The size, in bytes, of the heap. 
Example binary QECalc { 
source: 
Main.c 
heapsize: 1000000 // 1,000,000 bytes 
} 
LIBRARY 
This target creates dependencies and makefile commands for creating an aly 
to be used in the Taligent runtime system. 
Syntax library name { 
} 
Argument name Ther name e of the target. 
Examples library "MyLibrary”™ { 
source: 
LibraryInit.c 
Libraryl0.c 
} 
LINK 
This tag specifies all files to link within a target. 
syntax link: 
linkFiles 
Argument | linkFiles These files are linked with the listed source files and any other object listed in 


the target. If you omit this tag, nothing is explicitly linked in, and 
$UniversalLinkList is used. 
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Example This example produces a Taligent program (see “binary” on page 79) by linking 
with the files MenuLib and WindowLib, in that order. 


binary MyProgram { 


source: 
main.c 
Testl.c 
link: 
MenuLib 
WindowLib 
} 
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LOADDUMP 


This target creates build rules for creating a loaddump file with the specified 
headers. All targets built in a *. PinkMake file will have dependencies on the 
specified loaddump file. 


syntax loaddump JoadDumpFilePath { 
} 


Argument loadDumpFilePath The path of the loaddump file. If this file does not exist during the build’s 
Objects phase, the build creates this file. 


NOTE This syntax is not supported when building for Taligent Application 
Environment until the AIX development environment supports loaddump files. 
This feature is supported when building for Taligent Operating System with 
Comptech-on-AlIX. 


Example Create a loaddump file called MyProject.Dump in the directory pointed to by 
$(TaligentRoot)/Dumps: with the given header files included in it. The header 
files must be valid files in $TaligentIncludes or $TaligentPrivateIncludes. 


loaddump "$(TaligentRoot)/Dumps/MyProject.Dump" { 
Application.h 
Test.h 
Format.h 
Dialogs.h 
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Syntax | local: 


PON eA EE AOR LA OOKLA LEV EA LES ER ALISE SOR ELLA NOES RESALES LAIST ELLER CLEA LACES CALL ESS INI IEE ELA O EEA I ILI OSES EER EAS AEA AIII ELLIE A CTU R CED IDLE LIAS ESLER IIIA E CEE ER EKP HILAL LID DEEPA EEA IP EID IIIS ILIGIPEES EEN ESI LDIAE LISSA EDRIG EK IE DE IREIAEIS DISSE IIA CERISE RESET IAS AIL ERE ISR DA ASII ALA ERLE AERA EI AERP SAI ALI ESP EES EROS IEAECLSIR SSI A DL ONDE NRA ETE O ORO 


LOCALHEADER 
This tag specifies header files to export to the ]ocalheaderdir header directory. 


Syntax localheader: 
headerFiles 


Argument headerFiles The files to export to the 1ocalheaderdir directory. 


Examples Export the file Parents.h into a directory called : LocalHeaders:. If you omit the 
tag localheaderdir, the file is copied to the current directory. 


localheaderdir: ./LocalHeaders: 


parentobject MyParentObj { 
source: 

Parentl.c 

Parent3.c 

Parent5.c 
localheader: 

Parents.h 
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LOCALHEADERDIR 


syntax 


Argument 


Example 


This variable specifies the directory in which to export header files for the target. 


localheaderdir: JocalheaderPath 


localHeaderPath — The directory in which to export local headers. if you omit this variable, the 
headers are copied into the same directory as the source files. 
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syntax 


Argument 


Examples 
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With this target you can. specify you own build rules. Unlike start and end, the 


make target can appear anywhere in the input, and you can have multiple make 
blocks in the input. 


make { 
buildRules 


buildRules Your own build rules. 


make { 
Foo : Bar 
dF build rules 
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OBJECT (TAG) 
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syntax 


Argument 


Example 


sre rt OL PIL IL LPP OLM, 


Matted tare 


This tag specifies a target’s a dependency on object files that might be built 
within another target or project. | 


object: 
objectFiles 


objectFiles  _Link these object files in after any other files produced from specified source 


files within the target. | 


Create a dependency for MyLibrary on the file LibI0.c.o, which is an existing 
object from another target in the same project or another project. The explicit 
path to the object file is not required. 


library MyLibrary { 
source: 
Main.c 
object: 
./ObjectFiles:LibI0.c.o 
} 
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Syntax 


Argument 


Example 


This target combines files into a single library object for later use in another 
target or project. | 


object name { 


Combine three files into a single library object called MyObject, and copy it to 
$ObjDiz, if it is not the default. 


object MyObject { 
source: 
MySample.c 
MyOtherSample.c 
MyExtraSample.c 
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OBJECTDIR 
OBJECTDIR 
This variable specifies the directory for compile output and link input (object 
files) built within the current project. 
syntax objectdir: path 
sae 3 ee ey Pouca ca ae 
build stores these files within the current project in the :ObjectFiles: 
directory. 
Example Change the directory for built objects to MyObjects, one directory up in the tree. 
objectdir: ../MyObjects: 
NOTE In Release A, objectdir does nothing. This will be fixed in a later 
release. 
PARENTOBJECT 
This target is similar to the object target. It combines the specified files into a 
single library object, then it copies the built object into $ParentObjectDir as 
specified by the parentobjectdir variable. 
Syntax parentobject name { 
} 
aamen prs _ a. 
Examples Create MyObject from the compiled output of the three specified files, then copy 


it to the $ParentObjectDir directory. 


parentobject MyObject { 


source: 
MySource.c 
MyMenus.c 
MySample.c 
} 


.@ NOTE In Release A, parentobject does not export the created object to the 
_ parent directory. This will be fixed in a later release. 
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PARENTOBJECTDIR 
PARENTO BJECTDIR 
This variable changes the default directory in which to copy objects built from 
the parentobject target. 
syntax parentobjectdir: path 
Argument “path —— The directory for parentobject targets. If you omit this variable, the target 
copies the files to the ObjectFiles directory in the parent directory. 
Use only paths based on the current directory or a known directory tree. Do 
not use a declaration scoped to a specific user volume. : 
Examples Change the destination of pa rentobject copies to the ObjectFiles directory ina 


project called Sample in the parent directory. 


parentobjetdir: ../Samples/ObjectFiles/ 


CAUTION Do not depend on directories that can change in other projects. In 
example, if the Samples *.PinkMake file ever has a different $ObjDir (set with 
objectdir), this declaration might copy the built object to the wrong place. 
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PRIVATE 
Use this tag within a target to specify a dependency on header files located locally 
to the project. 
syntax private: 
headerFiles 
Argument headerFiles The local header files for the project. If you omit a header file, the build 
searches for the file in the local directory, then in $Taligentincludes, followed 
by $TaligentPrivatelncludes. When you include a header file, the build 
searches in the local directory only. 
Examples parentobject MyObject { 
source: | 
MySource.c © 
MyMenus.c // Look for MyMenus.h locally, then in the other directories 
MySample.c | 
private: | 
MySource.h // In local directory only 
MySample.h // In local directory only 
} 
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PRIVATEHEADERDIR 


syntax 


Argument 


Example 


This variable points to a directory to search for header files not in the source 
directory. 


privateheaderdir: path 


path An optional directory for the compiler to search for header files not in the 
source directory. 


PrivateHeader.h is not in the current directory. Without the reference to its 
location, compiles cannot locate it if main.c tries to include it. 


privateheaderdir: ../PrivateHeaders: 


library MyLibrary { 
source: 
main.c 
header: 
PrivateHeader.h // not in source directory 


eee ieee ee ieee eee er ee 


PROGRAM 


This is an obsolete target; use binary instead. 
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PUBLIC 


PUBLIC 


syntax 


Argument 


Examples 


SERVER 


Syntax 


Argument 


Examples 


This tag specifies which target headers the public tag can export to 


$TaligentIncludes. 


public: 
headerFiles 


Create a dependency for MyLibrary on the file LibI0. as usual. During the build’s 
Includes phase, export this file to $TaligentIncludes. 


library MyLibrary { 
source: 
main.c 
LibIO.c 
public: 
LibIO.h 
} 


This target creates dependencies for a Taligent application. All make 
dependencies for creating a Taligent application will be generated for you. This 
target builds a single executable with all sources linked in 


server name { 
} 


‘name -—_ The name of the target, and the name used as a prefix for makefile variables, 
include lists, and dependencies. : | 


An unsupported version of this target is userver. 


Produce a makefile for compiling the three source files, link them together with 
standard Taligent libraries, and create a main program binary and a shared 
library containing most of the code. Both of which contain the name “MyServer’”. 


server "“MyServer" { 
source: 
main.c 
Server.c 
ServerView.c 
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SOURCE 


syntax 


Argument 


Examples 
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SOURCEDIR 


syntax 


Argument 


Examples 
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This tag specifies source files within targets. The order of the files in the list is the 
order used to compile, link, and export. 


source: 
targets 


binary "“MyApp" { 


source: 
main.c 
TMyApp.c 
TMyView.c 
} 


This variable specifies the directory to search for source files. 


sourcedir: path 


path The directory for source files. If you omit this variable, the build searches in 
the same directory as the * .Make file. 


Base this path name on the current directory; do not rely on specific volume 


Change the default location of source files to a directory called Source within the 
current project. 


sourcedir: /Source 
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START 
START 


syntax 


Argument 


Examples 


SUBFOLDER 


syntax 


Argument 


Examples 


This custom target allows you to supply a block of make commands to copy into 
the beginning of the generated makefile. 


start { 
makeCommands 


makeCommnds — Any valid makefile syntax. CreateMake places this block directly in the 
generated makefile; pay careful attention to indentations and syntax. 


start { 
Foo : Bar 
d## build rules 


This tag identifies files within the export target to export to the ¢SubfolderDir 


within $TaligentBinaries. 


subfolder: 
exportFiles 


‘exportfiles --‘Thefilestoexport. = 


Export to the specified files to /MySamples/ within the $TaligentBinaries path. 


subfolderdir: /MySamples 


export { 

subfolder: 
MySamp1 eStuf f 
MyOtherSamp1eStuff 
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SUBFOLDERDIR 


syntax 


Argument 


Examples 


SUBPROJECT 


syntax 


Argument 


Examples 


CHAPTER 6 CREATEMAKE 
SUBFOLDERDIR 


This variable specifies the subfolder that is copied to from within an export 
block. | 


subfolderdir: directory 


See example for “subfolder.” 


"NOTE In Release A, binariessubfolder is a synonym that acts the same as 
subfolderdir. In later releases, binariessubfolder will not be a synonym. See the 
“binariessubfolderdir” on page 78 for more information. 


This target specifies subprojects to be included when the build system recursively 
builds directories. CreateMake places these subproject names in the 
$SubProjectList variable in *.Make files. 


subproject { 
subProjects 
} 


‘subProjects --‘Thesubprojectstobulld, = 


Generate the *.Make file with the three specified subproject/directory names in 
the $SubProjectList, and allow the build system to recursively execute the *.Make 
files in each of these subprojects whenever a make is done on is project. 


subproject { 
FancyText 
FancyDraw 
FancyPrint 
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TESTAPPLICATION 
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This target is similar to the binary target, but only gets built if “Makeit testing 
complete” is used. See “binary” on page 79 for more information. 


syntax testapplication name { 
} 
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TESTLIBRARY 
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This target is similar to the library target, but only gets built if “Makeit testing 
complete” is used. See “library” on page 84 for more information. 


syntax testlibrary name { 
} 
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TESTPARENTOBJECT 


This target is similar to the parentobject target, but only gets built if “Makeit 
testing complete” is used. See “parentobject” on page 89 for more information. 


syntax testparentobject name { 
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This target is similar to the testserver target, but only gets built if “Makeit 
testing complete” is used. See “testserver” on page 96 for more information. 


syntax testserver name { 
} 
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This target is similar to the binary target. See “binary” on page 79 for more 
information. 


syntax tool name { 
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TRIMDEPENDENCIES 


This target specifies header file paths to remove from the generated makefile. 


syntax trimdependencies { 
headerPaths 
} 


Argument | “headerPaths _—_—‘The list of header file paths to remove from the generated makefile. If you omit _ 
these paths, CreateMake includes the list of dependencies found in 
$Taligentincludes and $TaligentPrivateincludes 


By default, CreateMake includes the list of dependent header files found in 
$TaligentIncludes and $TaligentPrivateincludes. In most cases, these headers do 
not change and the extra dependencies result in larger make files that take 
longer to process. With trimdependencies, CreateMake removes any dependencies 
found in the list of header files from the generated makefile. 


Examples Strip out any dependencies that begin with $TaligentIncludes or 
$TaligentPrivateIncludes. You can do the same thing with any pathname, 
although generally, you only need to do this with the Taligent public and private 
includes. 


trimdependencies{ 
$(TaligentIncludes) 
$(TaligentPrivatelIncludes) 

} r 


CAUTION Be careful when using this feature. If a Taligent header used by one of 
your source files changes, that file will not be recompiled. You must manually 
force the file to be recompiled. 
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CHAPTER 7 


ANALYSIS TOOLS 


The heap analysis tools are a set of applications and classes that allow you to 
perform heap-related debugging and dynamic analysis operations. These tools 
are classes that you instantiate and control dynamically, and that use 
TMemoryHook to receive notification of allocations and deletions in a memory 
heap. 


The heap tools let you: 
# Track block allocation to see who allocated each block (when it is possible to follow 
call chains) through several levels of indirection. 


se Categorize all heap blocks to determine the type of blocks in the heap (for 
example, this block is a TStandardText). 


Browse heaps to see all the blocks in the heap, with their size, type, who 
allocated them, who deleted them, and so on. 


« Record memory usage over time by recording the relative time of each allocation 
and deletion for later analysis. 

« Zap memory by filling uninitialized and deleted blocks with odd byte patterns to 
catch bad pointer usage errors. 


Detect heap corruption by automatically checking the heap for corruption at each 
allocation and deletion. 
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There are two basic modes of operation: 


« Heap monitoring (the simplest operation) watches the heap at the event 
level and records allocation and deletion events. This produces an ASCII text 
file where each line in the file describes an eveni. 


# Heap analysis gathers the same data as heap monitoring, but processes the 
events further to produce annotated blocks within a model of the heap. It 
also detects anomalies in heap usage. When it stops watching, the analyzer 
writes a block-by-block description of the heap to an ASCII text file, where 
each line in the file describes a block in the heap. 


Tradeoffs Heap Monitoring 


the heap or that were most recently deleted. 
Reports more data, generates a larger datafile. | Reports less data, generates a smaller data file. 
Runs slower. Runs faster. 


Does not detect problems. Detects problems, such as double deletion. 


To use the local heap tools, modify your code to instantiate a heap tool object— 
either TLocalHeapMonitor or TLocalHeapAnalyzer. Once the object is 
instantiated, monitoring or analysis starts. When you destroy the object (such as 
if it goes out of scope) monitoring or analysis stops. 


Consider a class called TLeaksLikeASieve, which leaks storage when its Leak() 
method is called. The following code starts monitoring, calls the suspect method, 
then automatically stops monitoring when the monitor object goes out of scope: 


d#Finclude <LocalHeapMonitor.h> // for TLocalHeapMonitor 
void main() 
{ 
// Start monitoring; continue until object ‘monitor’ is destroyed. 
TLocalHeapMonitor monitor; 
TLeaksLikeASieve leaker; 
leaker.Leak(); 
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OVERVIEW - 


Both the heap monitoring tools and the heap analysis tools are available as 
remote (monitor a different team) or local (monitor the same team).There is no 
separate garbage finding tool. Garbage finding is available as a function of the 
other tools. 

TLocalHeapMonitor heap monitoring local team 


TLocalHeapAnalyzer heap analysis local team 


TLocalHeapMonitor and TLocalHeapAnalyzer have minimal dependencies. 


The heap tools contain these limitations: 


« The heap analyzer currently keeps data for only the most recently deleted 
heap block. As new blocks come in, old deleted block data is lost. 

« The heap tools consider the heap to be one logical object. In reality, the 
heap consists of two subheaps, the chunky and tree heaps. 


The TLocalHeapMonitor constructor has several options: 


enum EIgnoreOld { kReportOld = 0, kIgnoreOld = 1 }; 
enum EZapMemory { kDontZapMemory = 0, kZapMemory = 1 }; 


TLocalHeapMonitor(const char* outputFileName=0, 
EIgnoreOld ignoreOld=kReportold, 
EZapMemory zapMemory=kDontZapMemory, 
FrameCount depth=8, 
TStandardMemoryHeap* whichHeap=0) ; 


 OutputFileName specifies the name of the output file; the default is "heap_trace". 


« IgnoreOld, if set to kIgnoreOld, causes all blocks on the heap when monitoring 
was Started to be ignored. The default shows all such blocks. 

«: ZapMemory, if set to kZapMemory, causes the memory hook to fill blocks with 
recognizable patterns for the purpose of debugging reference-before- 
initialization and reference-after-deletion errors. 


Uninitialized memory gets filled with the pattern 0xDEAFBEED. 
Deleted memory gets filled with the pattern 0xFEEDDEAD. 


« Depth is the maximum count of functions which the stack crawls will contain. 
Increasing this option provides more data in some cases, but takes up more 
memory and slows down the tool. 

ze WhichHeap specifies which heap to monitor. If unspecified, the default heap is 
monitored. | 
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Heap monitoring 
file format 
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The TLocalHeapAnalyzer constructor has several options: 


enum EIgnoreOld { kReportOld =.0, kIgnoreOld = 1 }; 
enum EOnlyGarbage { kA11Blocks = 0, kOnlyGarbage = 1 
enum EZapMemory { kDontZapMemory = 0, kZapMemory = 1 


} 
TLocalHeapAnalyzer(const char* outputFileName=0, 
EIgnoreOld ignoreOld = kReport0Old, 
EOnlyGarbage onlyGarbage = kA11Blocks, 
EZapMemory zapMemory = kDontZapMemory, 


FrameCount depth=8, 
TStandardMemoryHeap* whichHeap=0) ; 


 OutputFileName specifies the output file name; the default is "heap_analysis". 
# OnlyGarbage, if set to kOnlyGarbage, causes the analyzer to list only blocks 
which were allocated, but not deleted. The default lists all blocks in the heap. 


All other options are the same as those for TLocalHeapMonitor. 


In heap monitoring output files, each line describes an event that indicates that: 
# A block was allocated. 
# A block was deleted. 
# A block was already in the heap when monitoring was begun. 
# The heap was corrupted. 


Here is an example of each type of event: 


Thread Time of event Address Size Type Stack crawl 
2-22982 759537687555872 0xb2362718 del TIterator TArraylIterator... 
2-22982 | 759537687558595 0xb2362950 12 novtbl THybridNumber... 
0-0 old | Oxb24020d0 48 TLocalSemaphore 


Thread—the identifier for the thread that called new() or delete(). For old blocks, 
this field is 0-0. 


Time of event—the time, in microseconds, of the event. Use this value to determine 
the order of events and to compute the time between events, such as to find the 
age of a block at deletion. For blocks already on the heap when monitoring | 
starts, this field is old. 


Address—the address of the first byte of the block. 
Size—the size of the block in bytes. If this is a deletion event, the size field is de]. 


Type—the type of the block, for blocks that represent C++ objects. If the v-table 
pointer is NIL, this field is novtb1. If the v-table pointer is non-NIL, but it cannot 
be followed to a valid destructor, this field is notype. Note that only deletion 
events and pre-existing block events can have type information. Allocation events 
are always novtb1 because the constructor, if any, has not been called yet. 
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Stack crawi—the function that called new() or delete(). For old blocks, this field is 
empty. The stack crawl consists of several function names, separated by 'I' 
characters. The first function name is the innermost. It was called by the next 
function name, and so forth. In the example, the stack crawls have been 
abbreviated. A full stack crawl looks like this: 


TArrayIterator: :~TArrayIterator()|THybridNumerals: :AddFormattingPairAbsolutely(unsigned 
short, 1long)|THybridNumerals: :AddFormattingPair(unsigned 
short,long)|THybridNumerals::CreateStandardHexNumerals()|TTieredTextBuffer: :NumberFormat 
()|TTieredTextBuffer: :operator<<(const long) |TTieredTextBuffer: :operator<<(const 

int) |TLocalHeapMonitorTest: :ShowMem( void*,1ong) 


LEP LISLE OPEB LOMO M OOOO LLL ELIE OIL MEDEA P PILL LL LLLLOLILLLLILLPDILLLOILD Pe 


Heap analysis output files have two sections: the anomaly section and the heap 
dump. In the anomaly section, any anomalies which were detected are described. 
See“Dynamic error detection” on page 105 for explanations of the anomalies 
that can be detected. 


In the heap dump section, each line describes a block in the heap. By default, it 
displays all blocks of the heap. You can also specify to ignore old blocks, or to 
show only undeleted blocks. Use the latter for finding storage leaks. See 
“TLocalHeapAnalyzer” on page 102 for more information. 


Allocation Deletion 
: : ! i Bs 
Address Size Type Age Thread Time Stack Thread Stack 
Oxb0c496b4 1028 TFoo 285198 2-22981 759... TLocal... notask nochain 


Address—the address of the first byte of the block. 
Size—the size of the block. 


Type—the type of the block. If the v-table pointer is NIL, this field is novtb1. If the 
v-table pointer is non-NIL, but it cannot be followed to a valid destructor, this 
field is notype. Note that only deletion events and pre-existing block events can 
have type information. Allocation events are always novtb1 because the 
constructor, if any, has not been called yet. 


Age—the block in microseconds. If the block has been deleted, this is the age of 
the block when it was deleted. 


Allocation thread—the thread that allocated this block. 


Allocation time—the time of the allocation, in microseconds. Use this to determine 
the order in which blocks were allocated. | 


Allocation stack crawi—the function that allocated this block. 


Deletion thread—the thread that deleted this block, or notask if the block has not 
been deleted. 


Deletion stack crawi—the function that deleted this block, or nochain if the block has 


not been deleted. 
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Both the ences analyzer and the heap monitor detect ere corruption by calling 
TMemoryHeap::Check after each allocation event and before each deletion 
event. When the heap is found to be corrupt, the tool writes a message similar to 
the following to the output file and echoes it to the console. In heap monitor 
output files, an asterisk (*) precedes each subsequent line to indicate that the 
corrupt heap. 


KKEKKEKEKKKKKKKKKKEKKEKEKKEKKKKEKRKERKEEKRERKEKEKEKKEKEKKKRKEKEKRKEKERKEKKEE 
k*kx 


xxx Tree heap corrupt with error 5. 


xxx See PrivateIncludes/TreeHeapExceptions.h for enums. 
Kkk 


KEKEKEREREKERREEKERERERRRREREERERERKRRREKKRKRERKRKREKKEREREREERER 


The message states that either the tree heap or the chunky heap is corrupt, and it 
specifies an error number. This number is the return value of the Reason () 
method in the TChunkyHeapCorrupted or TTreeHeapCorrupted exception 
object. To determine its meaning, refer to TreeHeapExceptions.h or 
ChunkyHeapExceptions.h in the PrivateIncludes directory. 


If you have a heap corruption bug, use a heap monitor to debug it. Although the 
heap analyzer also notifies you of heap corruption, it does not help you pinpoint 
the problem. The heap monitor shows the pattern of allocations and deletions 
leading up to the corruption. 


In order to debug the corruption, examine the event before the corruption 
message. If the message that the heap is corrupt occurs before any other events, 
you must start monitoring earlier. Starting with the code indicated by the 
preceding event's stack crawl, trace forward until you find the corruption. You 
can either read the source code or step in a debugger. The bug will usually 
involve violating array boundaries or misusing pointers. If you see another heap 
event (allocation or deletion), backup; you have gone too far. 


On AIX, the heap tools trigger and catch segment violation signals (SIGSEGV) | 
during the dynamic typing of blocks. Usually this will be invisible to you. | 
However, if you run the heap tools under a debugger, it will trap the signal 

SIGSEGV, and you will enter the debugger that is executing the heap tool code. 

To avoid this, tell the ereueee to ignore the signal 11, SIGSEGV. For example, 

in the shell, use 


xdb -i11 Foo & | | ! 


where Foo is your program’s name. Within dbx, use: 


‘ignore 11 
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Dynamic typing The heap tools attempt to determine the type of blocks in the heap (the class 
they instantiate). For raw block events, all allocation events have no type 
information because they represent unconstructed objects. Many blocks cannot 


be typed. 
Dynamic error Dynamic error detection, or discipline, is the programmatic detection of errors in 
detection either the heap code itself, or calls to the heap indirectly through operators new 


and delete. 


The heap analyzer has an extensible discipline architecture consisting of a set of 
instances of concrete subclasses of THeapDiscipliner. (These objects are equal, 
by default, if they are of the same type.) This class has the virtual method 
CheckBlockEvent; subclasses override this to provide discipline behavior. 


The heap model has several varieties of discipline are built into it (there is no 
THeapDiscipliner subclass for these anomalies): 


Bad address deletion—the detection of addresses that do not correspond to allocated 
blocks in the heap. A subset of this is double deletion detection. Therefore, these 
two anomalies are detected by the same class in an either-or fashion. 


Double deletion detection—the detection of two deletions of the same block. This is 
complicated by the fact that the heap allocates blocks to the same address once 
that address is free. The tool tracks old blocks that have been deleted. When a 
delete of the wrong type or is unmatched by a corresponding new occurs, it is an 
error. 


Non-unique allocate return values—according to the The Annotated C++ Reference Manual 
(by Ellis and Stroustrup), operator new must return unique values (until such 
blocks are deleted). The toll checks this by verifying new allocations against live 
blocks in the existing block map. 


Heap corruption—detected by calling TMemoryHeap::Check at each allocation and 
deletion. 
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Garbage finding 
and-sweep garbage finding looks in the address space for pointers to blocks, and if 
there are no pointers to a block, considers the block garbage. This technique 
searches other blocks in the heap, local variables on the stack, and the static data 
areas. Allocation-deletion matching is a simpler scheme that considers a block 

_ garbage at some point in time if it has been allocated but not deleted. The latter 
scheme has fewer dependencies, and so it is more portable, but it gives more 
false positives. | 


Garbage finding is not implemented as a subclass of THeapDiscipliner. It is 
handled separately. 
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The main classes are TLocalHeapMonitor, TLocalHeapAnalyzer, and 
THeapMirror. In addition, these classes pull in a few auxiliary classes. 


heaps in the same team under programmatic control. 


TLocalHeapMonitor TLocalHeapMonitor begins monitoring of a TStandardMemoryHeap when 
TLocalHeapMonitor object is constructed. Destroying the object terminates 
monitoring. At construction time, you can specify the name of the output file, to 
ignore old blocks, to zap memory, and the maximum depth of stack crawls. 


class TLocalHeapMonitor 


1 
public: 
enum EIgnoreOld { kReportOld = 0, kIgnoreOld = 1 }; 
enum EZapMemory { kDontZapMemory = 0, kZapMemory = 1 }; 
TLocalHeapMonitor(const char* outputFileName=0, 
EIgnoreOld ignoreOld=kReportold, 
EZapMemory zapMemory=kDontZapMemory, 
FrameCount depth=8, 
TStandardMemoryHeap* whichHeap=0) ; 
virtual ~TLocalHeapMonitor(); 
J 
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TLocalHeapAnalyzer TLocalHeapAnalyzer begins monitoring and analysis of a TStandardMemoryHeap 
when a TLocalHeapAnalyzer object is constructed. Destroying the object 
terminates monitoring. At construction time, you can specify the name of the 
output file, to ignore old blocks, to show only garbage, to zap memory, and the 
maximum depth of stack crawls. 


class TLocalHeapAnalyzer 


{ 
public: 
enum EIgnoreOld { kReportOld = 0, kIgnoreOld = 1 }; 
enum EOnlyGarbage { kA11Blocks = 0, kOnlyGarbage = 1 }; 
enum EZapMemory { kDontZapMemory = 0, kZapMemory = 1 }; 
TLocalHeapAnalyzer(const char* outputFileName=0, 
EIgnoreOld ignoreOld = kReportold, 
EOnlyGarbage onlyGarbage = kA11Blocks, 
EZapMemory zapMemory = kDontZapMemory, 
FrameCount depth=8, 
TStandardMemoryHeap* whichHeap=0) ; 
virtual ~TLocalHeapAnalyzer(); 
73 


Heap monitor classes § These are the heap monitor classes. 


TBlockEvent TBlockEvent: public MCollectible represents one of three possible occurrences 
in the heap: a block allocation, a block deletion, or the registration of a pre- 
existing block. The last type of event is needed because when watching starts, 
there are blocks in the heap already for which no context information is known. 


Block events have the following state information: 
# The thread in which the event happened, a TSurrogateTask. 
« ‘The time of the event, a TTime. 
# The first byte address of the block in question, a void *. 
# ‘The length of the block in bytes, a size_t. 
# The object’s v-table pointer, if any, a void *. This field does not exist for 
allocation events because newly-allocated blocks contain garbage. 


« The call chain of the event, a TCallChain. This call chain is limited toa 
maximum frame depth which is a constructor parameter to TBlockEvent. 
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TBlockEventHandler TBlockEventHandler: public MCollectible is an abstract base class that defines 
protocol for classes that process block event information. Such classes might, for 
example, write block event data to a text file, or use the block events to maintain 
a dynamic model of the heap’s state. | 


class TBlockEventHandler : public MCollectible { 
public: 
// Framework methods. These will be called in the order: HandlelInitialize, 
// HandleBlockEvent (for each event), HandleFinalize. 
virtual void HandleBlockEvent(const TBlockEvent&, TAddressPeeker&) = 0; 
virtual void HandleInitialize(TAddressPeeker&) {}; // Override if desired 
virtual void HandleFinalize(TAddressPeeker&) {}; // Override if desired 
ie 


TAddressPeeker TAddressPeeker allows you to perform address-space-specific operations from 
another team. It maps addresses to symbolic names (function names), finds 
destructor addresses of objects, and reads the contents of memory in the remote 
address space. Use this class whenever freezing occurs in order to convert 
addresses in the target team into text symbols. 


TAddressPeeker caches function names it finds, under the assumption that the 
same address will be looked up frequently. Because of this caching, instances of 
TAddressPeeker should be shared; that is, if multiple clients on a team need its 
services, they should share a single instance of it. 


TAddressPeeker uses a TTeamHeapMonitor, a client of 
T'TeamHeapMonitorDispatcher, to do its work. 


class TAddressPeeker { 
// This 18 not an MCollectible. Do not copy it, assign it, stream it, clone it, 
// or do any other MCollectible operations. 
public: 
TAddressPeeker(TTeamHeapMonitor* aliasedMonitor); 
virtual ~TAddressPeeker(); 


// Functions in remote address space. These methods are multithread-safe. 

// DescribeFunction returns an unmangled function name, which it also caches 
// for subsequent calls. DescribeCal]Chain returns a tab-delimited list of 
// function names for a call chain. Describe object returns the class name 
// of an object on the heap. 


const TText& DescribeFunction(const void* address); 

const TText& DescribeCallChain(const TCal1Chain&); 

const TText& DescribeObject(const void* address); 

const TText& DescribeVTable(const void* address, const void* destructor=0); 
void CopyMemory(void* localCopy, const void* address, size_t bytesToCopy); 
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Heap analyzer classes These are the heap analyzer classes. 


THeapBlock THeapBlock: public TAbstractHeapBlock represents a single block within a 
THeapMirror. It has state: live or frozen, allocated or deleted, first byte address, 
size, time of allocation, age, allocation context and deletion context, dynamic 
type. If it is frozen, the context information is flattened to text; otherwise, it 
consists of addresses in the target teams address space. 


class THeapBlock: public TAbstractHeapBlock { 

public: | 
// Construct from the allocation event. Normally this is a allocation 
// or an already exists event. This can also be a deletion event, which 
// is anomalous, but will be handled correctly. 
THeapBlock(const TBlockEventa&); 


// Canonical methods 

THeapBlock(const THeapBlock&) ; 

THeapBlock& operator=(const THeapBlock&); 

virtual ~THeapBlock(); 

virtual TStream& operator>>= (TStream& towhere); 
virtual TStream& operator<<= (TStream& fromwhere) ; 
MCollectibleDeclarationsMacro(THeapBlock) ; 


// Deletion 
void Delete(const TBlockEvent&) ; // Delete using the block event 
void DeleteAnomalous(); // Mark as deleted; we never got deletion event! 


// Characteristics 

// Boolean IsDeleted() const; // Inherited 
// void* GetAddress() const; // Inherited 
size_t GetSizeInBytes() const; 

TTime GetAllocationTime() const; 


TTime GetAge() const; // computes on the fly if needed 

void GetClassName(TText&); // dynamic type: THIS IS USELESS AT THIS POINT 
// Describe 

void DescribeBlock(TAddressPeeker&, TText&) ; // address size type age 

void DescribeAllocation(TAddressPeeker&, TText&) : // thread time stackcrawl 

void DescribeDeletion(TAddressPeeker&, TText&) ; // thread time stackcrawl 


void Describe(TAddressPeeker&, TText&, UniChar separator); 


// Context 

const TCallChain* GetAllocationContext() const; 
const TCallChain* GetDeletionContext() const; 
TSurrogatethread GetAllocationThread() const; 
TSurrogatethread GetDeletionThread() const; 


// Freezing 
Boolean IsFrozen() const; 
void Freeze():; 

ys : 
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TAbstractHeapBlock 


MHeapDiscipliner 


SIS TOOLS 


TAbstractHeapBlock: public MOrderableCollectible represents a block on the 
heap, and is an abstract base class descending from MOrderableCollectible. It 
has only two pieces of state data: its address and whether or not it is deleted. The 
latter defines canonical comparison methods (IsEqual, IsGreaterThan, 
IsLessThan) based on the address and deletion status. This allows you to search 
for a block in a collection at a certain address—either a deleted or a live block. 


MHeapDiscipliner: public MCollectible is an abstract class that defines the 
protocol for classes that monitor the correctness of heap behavior and usage. 
The method CheckBlockEvent verifies that the given block event is valid on the 
given heap model. If there is a pre-existing block at the address of the event, it is 
passed in. If CheckBlockEvent detects a problem, it creates a new 
THeapAnomaly on the heap and returns it; otherwise it returns 0. 


class MHeapDiscipliner : public MCollectible { 


THeapMirror 


public: 
virtual THeapAnomaly* CheckBlockEvent(const THeapMirror& heapBeforeTheBlockEvent, 
const THeapBlock* preExistingBlockOrNil, const TBlockEvent& newEvent) = 0; 
VersionDeclarationsMacro(MHeapDiscipliner); 
yj 


THeapMirror: public MCollectible is a model that mirrors the contents of the 
heap. It maintains a sorted list of all blocks in the heap. When a block is deleted, 
it keeps the block in the model until a new block is allocated at the same address. 
This allows discipliners to differentiate a double deletion from a deletion of a 
non-block address. In fact, the mirror maintains deleted blocks until a new block 
is allocated and deleted. the mirror can store up two blocks at the same address: 
the last block that was deleted, and the current live one. 


€ 4 NOTE Differentiating a double deletion from a deletion of a non-block 
address is insufficient in some cases. An example of this is if you allocate block 
#1, then delete it, then allocate block #2 at the same address, then delete it, then 
allocate block #3 at the same address, then delete a pointer to block #1. This final 
deletion will be incorrectly reported as a double deletion of block #2 rather than 
of block #1. 


The heap model has data for each block in the heap. It maintains state 
information for the heap as a whole: whether it is live or frozen. If live, the heap 
has pointers into the team being watched and also contains an anomaly list. 


If the heap is live, it is connected to a team, and contains a TAddressPeeker 
which allows it to resolve addresses to symbolic names and retrieve memory 
contents. 
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class THeapMirror: public MCollectible { 

public: 
// Canonical methods 
THeapMirror(); 
THeapMirror(const THeapMirror&) ; 
THeapMirror& operator=(const THeapMirror&); 
virtual ~THeapMirror(); 
virtual TStream& operator>>= (TStream& towhere) ; 
virtual TStream& operator<<= (TStream& fromwhere); 
MCollectibleDeclarationsMacro(THeapMirror); 


// Accessing blocks 

Titerator* CreateBlockIterator() const; // Exception on failure 
THeapBlock* FindBlockAt(void* address) const; 

THeapBlock* FindDeletedBlockAt(void* address) const; 

void AdoptBlock(THeapBlock*) ; 

void DeleteBlock(const THeapBlock&); 

long GetBlockCount() const; 

const TSortedSequence& GetBlocks() const; 


// Connect/disconnect 


Connects the mirrortoan-——~_—_ enum EState {kConnected, kNotConnected, kBusy}: // Busy means in transition 
existing, running team \_- void ConnectToTeam(const TthreadHandle&, FrameCount maxDepth) ; 

w-~ void LaunchAndConnectToTeam(const char* teamName, FrameCount maxDepth); 
Launches a new team and ————~" void Disconnect(Boolean freezeModel=TRUE) ; 
watches it until it dies void WaitForDisconnect(); 


// Information 

EState GetState() const; 

TthreadHandle GetTargetTeam() const; // Invalid team if not connected 
void GetTeamDescription(TText&) const; 


Dumps a text description of ——----- void Describe(); 
the heap to a text file 
// Freezing, reset. Later may add Unfreeze(TthreadHandle). 
Boolean IsFrozen() const; 
void Freeze(); 
void Reset(); // Clear out all blocks and anomalies 


// Discipliners 
TIterator* CreateDisciplinerIterator() const; // Exception on failure 


void AdoptDiscipliner(MHeapDiscipliner*) ; // Adds discipliner to set 
Updates the internal model, -~~. // Anomalies ; 

\ TIterator* CreateAnomalylterator() const; // Exception on failure 
and also passes on the \ 

\ void AdoptAnomal y(THeapAnomal y*); // Adds anomaly to list 
event to the attached set of \ F e : a : 
THeapDiscipliner : // Called by THeapMirrorAgent 
subclasses for checking “—- vOid IncorporateBlockEvent(const TBlockEventa&) ; 
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THeapAnomaly 


THeapMirrorException 


THeapAnomaly: public MCollectible is an abstract class associated with 
THeapDiscipliner. Each THeapDiscipliner, if it finds an anomaly, constructs and 
returns a corresponding subclass of THeapAnomaly. The heap model maintains 
a list of such anomalies and displays them graphically. Anomalies can be 
connected to specific THeapBlocks. | 


Three concrete classes are TDeleteTwiceAnomaly, TDeleteNonBlockAnomaly, 
and TAllocTwiceAnomaly. | 


class THeapAnomaly: public MCollectible { 
public: 
// Canonical methods 
THeapAnomaly(const THeapAnomaly&); 
THeapAnomaly& operator=(const THeapAnomaly&); 
virtual ~THeapAnomaly(); 
virtual TStream& operator>>= (TStream& towhere) const; 
virtual TStream& operator<<= (TStream& fromwhere) ; 


// Description 
void SetDescription(const TText&); // Subclasses should call in their ct 
void GetDescription(TText& toReceiveDescription) const; 


// Do not delete result of GetAssociatedBlock. 
THeapBlock* GetAssociatedBlock() const; // 0 if none 


protected: 

THeapAnomaly(const THeapBlock* associatedBlock); 
private: 

THeapAnomaly(); // Disallowed; not defined 
i Be | 


THeapMirrorException: public TStandardException is the exception class thrown 
by THeapMirror. It includes codes for invalid team, already watching team, not 
watching team, could not create iterator, block not found, and freeze without 
peeker. 
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Tool utility classes Classes in this section are defined in the ToolUtilities project. 


TCallChain TCallChain: public MCollectible represents a call chain or stack crawl at a 
particular point of execution. It has methods that update its contents to reflect 
the current call point, and can skip some number of frames to get to the 
interesting part of the stack. TCallChain has a variable depth (it can grow or 
shrink at runtime) but it only changes its depth during copying or assignment. 
Otherwise it traverses the stack until its buffer is full. The size of this buffer is the 
maximum frame depth, and is a settable parameter in the heap tools. 
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CHAPTER 8 


TEST TOOLS 


The test tool included with Release A is TCL. 
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TCL 7.3 (pronounced “tickle”) is a public domain scripting language from UC 
Berkeley. It is specifically written as a tool to integrate development tools. Its 
syntax is much like that of other UNIX shells (csh, sh, etc.), but it provides 
several specific advantages over the others, most notable is that it is highly 
extensible, portable, and embeddable inside of other programs. 


Getting started with TCL is easy, but like any programming language, learning to 
take full advantage of its power takes time. Start with basic scripts, and learn 
more as you go. 


*NOTE This documentation is intended to get you up and running quickly as 
a tester using TCL. This is not a language reference or tutorial, but it does cover 
basic usage of the language for testing purposes. 


aR P EE. 
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ttclsh is a variant of the standard tclsh provided with the TCL distribution (the 
extra “t” is for Taligent). This implements TCL, and should be available on your 
AIX system. ttclsh includes several important TCL extensions: -[incr tcl] (an 
object programming extension), Test Framework extensions, and (eventually) 
extensions to allow distributed script execution. 


You can invoke ttclsh interactively, in which case it works much like csh. This 
can be handy when debugging scripts. 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION TALIGENT INTERNAL TOOLS 


116. CHAPTER 8 TEST TOOLS 


TCL 
To run ttclsh on UNIX systems, all test script files should have execute | 
permissions and have a first line that reads: 
#1 /usr/taligent/bin/ttclsh 
On native systems, TCL will be the only scripting engine available, and this line 
will be ignored. | 
“NOTE Test scripts should have a .tc1 suffix so that its type of script is 
obvious. 
unning tests from Run tests from TCL by calling tal_runtest. tal_runtest is a wrapper for runtest; 
TCL scripts all runtest command options work with tal_runtest. 


tal_runtest -echo d -t TMyTest MyTestLib 


Before calling tal_runtest, start the Taligent AIX layer with StartPink. 


AINA L EEA AREA EOL REE CEN DERE EE AROS a a ae 


Learning more Like other UNIX scripting languages, TCL provides a great deal of support for 
about TCL complex scripts, including control flow structures, user-defined procedures, and 
local and global variables. Use these features when writing test scripts; eee 


You can find out more about the features by reading the TCL documentation, 
which is available online or in printed form. The online documentation is in man 
pages. You can find useful TCL man pages in the /usr/taligent/man/manl and 
/usr/taligent/man/mann. 


There are also raw PostScript — documents in: 
$TaligentRoot/Taligent/DevelopmentTools/Platform/AIX/tcl/docs 


To get printed versions of these documents, request them from your Area 
Assistant. Though there is a 300 page book on TCL available for reference, due 
to copyright restrictions, we are unable to make copies for individuals. However, 
you can copy via FTP from: 


harbor.ecn.purdue.edu: /pub/tcl/sprite-mirror/book*.ps.Z 


These files can be uncompressed and printed on a LaserWriter printer using 
ShowPages, DropPS, or equivalent utility. Remember, though, that it is 300 
pages! 


{6 NOTE If you do not have physical access to Taligent, you can obtain the TCL 
_ documents from the same ftp site. 


TALIGENT INTERNAL TOOLS TALIGENT CONFIDENTIAL: REGISTERED INFORMATION PRELIMINARY 


rere isin eer erecemanee epee Tiere cotta herrea ceesaat: TEEPE TTT ET STE TET T TTT TT SST SESS 


Ensuring portability 


CHAPTER 8 TEST TOOLS 
TCL 


TCL allows you to execute any UNIX command. However, do not use any 
commands other than built-in TCL commands in your scripts, because not all 
UNIX commands are portable to other systems. The only exception to this rule is 
launching Taligent Application Environment applications, because these should 
be available on any system you test. 


Here are some commands to watch out for; do not use these commands in your 
scripts: 


1s 

cat 
grep 
awk 
sed 
per | 
find 


A TCL example 


PRELIMINARY 


This example TCL script is an excerpt from the much larger Test Framework test 
script, but it is a complete example in and of itself. The only changes needed 
from the sh original were adding the header and doing a search and replace 
from RunTest to tal_runtest and from echo to puts: 


#!/usr/taligent/bin/ttclsh 
dF $Revision: $ 


ff $-- 22-2222 e ee ee eee eee eee eee 
# | Test script for TestTestFrameworkLib 

# | Alan Liu 

4 | Copyright (c) 1992-1993 Taligent, Inc. 

i 


| 
| 
## | This script relies on the libraries TestLib, BaseTestLib, & 
| 
| 
| 
| 


4 | TestTestFrameworkLib. 

dt | History: 

d 12/09/93 ET Changed to shell script for AIX. 

‘li 12/20/93 AGS Converted to tcl 

jf} +----------- 2 ee ee rr re rr rr er ee ee ee ee ee ee ee fe --e-ee 


puts "iHHF TestTestFrameworkLib.Script - Start..." 


puts “dHHF TNothingTest"™ 
tal_runtest -log -t TNothingTest TestTestFrameworkLib 
tal_runtest -log -e t -t TNothingTest TestTestFrameworkLib -n 100 
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CHAPTER 9 


XCDB 


Xcdb is a graphically oriented symbolic debugger for C, C++, and FORTRAN 
programs running under AIX Version 3, Release 2 (and later). It is a standalone 
program, not a windowed front-end to dbx. Xcdb has the breakpointing, stepping, 


and traceback capabilities common to most debuggers, but particular attention __ 


has been paid to presentation and ease of use. Xcdb understands the name 
mangling schemes used by x1C for typesafe linkage. It can display C++ class 
objects, display and set breakpoints in template instantiations, and display the 
internal contents of virtual function tables. 


Xcdb runs under the X11 Release 4 (and later) windowing system and makes full | 


use of X capabilities. Since Xcdb runs in a separate X window from the program 

being debugged, each has unrestricted use of the screen, mouse, and keyboard. 
The debugger is mouse driven, meaning that most interactions are performed by 

positioning the mouse over an appropriate screen location and clicking a key or 
button. Xcdb requires little or no typing. 


With Xcdb, you can: 

« Inspect the local environment of any function in the call chain and display 
the format (signed, unsigned, hex, etc.) of any individual variable 

« Expand aggregate objects (classes, structs, unions, and arrays) to reveal 
arbitrary levels of detail 

« ‘Tailor window layout to your preferences by making appropriate entries in 
your .Xdefaults file 

# Dereference pointers to reveal pointed-to objects 

« Obtain the type, size, and address of any object 

# Call upon C++ class instances to display themselves 
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Vi 


When Xcdb traps a program interruption, either planned (by setting breakpoints) 
or unplanned (due to program exceptions or external signals), Xcdb makes the 
program state available for inspection. The display includes window panes for: 

x: A traceback of uncompleted function calls 

« A view of the source code for the current function, positioned at the current 

line 

# A view of variables defined in the scope of the current function 

# A view of variables defined outside the scope of any function 
If the program interruption is of a type that allows execution to be continued, 
then you can resume program execution, perhaps after setting or clearing 


breakpoints. You can either ignore the signal that caused the interruption or pass 
it to the program. 


Here is a typical display following a program exception. 
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Pe + 
Callers & Commands ® Files 
a 


s SIR AAAAIE worenns prcmense ERRNO REI 


Externals Bais : 


An iconized 
window. 
: BERRIES IRAP B IAEA POO GEIS BISA TPS SEPIA RN PETE P SIE PEN SEAN PISS EI SIS PN SEDI IIIA OO OO Left-click the 

: stuff, - icon to convert 
it to a normal 
window. 
Left-click the 
title bar to 
convert it to an 
icon. 


The pointing hand 
icon marks the 
source line 
corresponding to 
the current 
instruction. 
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| program suoppe’ during trace ak, Siena’ Lats SIGSEGY cea Violen 
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Locals for subr() of stuff.c » Callers Commands 

isubr Run E 
Line stepf 
Call step} 
pointer dReturn st 
More detail 1 
Less detail ‘Se even OOOO HORM ORHS BBacronceceons 
Format as... = en 


bits 
...string 
a array 
...pointer 
... address 
..+.type 
..,8ize | 
... default 
‘|Select subrange~ 
‘\change value — 
 |Change type 

|Set mark 
Use mark . 


Ae 
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SETUP 


PPTL T TT TET 


You must be running X11 Release 4 or later, with a graphics display and mouse. 


Use two displays if you will be debugging programs that create virtual hft 
terminals (graPHIGS programs, for example). One display should be used for X 
and the other for the application program. 


PL LEL ELLIOT NOELLE CELE EEL EEP LLL OL OL 


Download xcdb6000.tarbin asa binary file, and process it with the tar. For 
example, if you have xcdb6000.tarbin and in /tmp, use the following commands 
to extract the tarfile contents into /usr/bin: 


SU 3 ## become super user 
cd /usr/bin ## go to destination directory 
tar xvf /tmp/xcdb6000.tarbin ## extract contents (Xcdb) 
dF now click Ctrl-d to become normal user again 


Xcdb lays out its window panes according to a predefined format. The layout is 
scaled to fit the window size specified by your .Xdefaults file, bya command line 
parameter, or by the window manager. “Customization” on page 140 describes 


how you can change the layout (and colors) to your preferences. 
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Signals 


ff 
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To be able to interrupt your program or Xcdb asynchronously from the keyboard, 
define appropriate signal keys using stty. This document assumes that Ctrl-c 
generates an INTR signal and that Ctrl-\ generates a QUIT signal. These are the 
default values on AIX systems. 


Compile and link the program to be debugged with the -g option in order to 
make the necessary symbolic information available. Do not use -0 with -g. Xcdb 
cannot reliably debug the resulting program due to code and register motions 
introduced by the compiler’s optimizations. 


TALIGENT INTERNAL TOOLS TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


Pees 


PRELIMINARY 


ferent sees oe AEP REFER aie ep petp aS 


Arguments 
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xcdb [-geometry WxH+x+Y] 


[-font fontname] 
[-title title] 
[-bw] 


= 
| 
= 
Oo 
4 


dirname] 
pid] 
funcname | 
numelts] 
numcalls] 
numdetails] 
numbreaks ] 
i signo] 
fetcher] 


SMa aaa ee eee 
! 
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[-p] 
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—font fontname 
—title title 

—bw 

—wb 


-I dirname 


—a pid 


—r funcname 


—geometry WxH+X+Y A window size and position, overriding the specification in .Xdefaults (if any). 


The name of a font, overriding the specification in .Xdefaults (if any). 
A title to place on the window border. 

Use a black on white color scheme. 

Use a white on black color scheme. 


A directory to search for source files which cannot be found in the current 
directory (multiple -1 flags are cumulative; up to 50 directories will be searched 
in the order listed). You can also specify the search path after Xcdb is running: 
see “Preferences” on page 138. 


The ID of an existing process to attach to, instead of starting a new process. 


Specifies how far to run the program’s initialization routines. Normally the 
program runs to the symbol main, the standard starting point for C programs. To 
stop at some other function, specify its name. For example, to stop at the 
program’s first instruction, specify-r \verb, _,start. 

To stop at the function which initializes C++ static objects, specify 

-r \verb,__,C\verb,_,runtime\verb,_,startup. 
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—e numelts 


—c numcalls 


—d numdetails 


—b numbreaks 


—i signo 


~—f fetcher 


—n 


—p 


program 


args 


The maximum count of elements to display for any array (default is 1000). 


The maximum count of functions to display in the function call traceback (default 
is 20). | 


The count of detail levels to add (or remove) when More( or Less) detail is 
selected from a data object formatting menu. 


The maximum count of breakpoints that can be set simultaneously (default is 50). 


The number of a signal to ignore and pass to the program (multiple -i flags are 


cumulative). 


The name of a program to call when the debugger needs to display a source file 
that it cannot find in the regular unix file system. The debugger invokes the 
program, passes it the name of the desired file as a command line argument, and 
display its output in the Listing window pane. Use this feature if, for example, 
your source files are kept in an SCCS or RCS database. 


Write window layout information to a file named samp1e-1ayout when the 
debugger exits. You can then copy this file into your .Xdefaults file where it 
will be read when you next run the debugger. See “Customization” on page 140. 


Run quietly, only revealing the debugger if the program being debugged stops 
due to a signal or runtime exception. 


Run verbosely, print status information and commentary while running. 


Do not include shared object file symbols when loading the program. For large 
shared libraries, this option can significantly speed up the debugger and reduce 
the amount of virtual memory used. ; 


Ignore compiler-generated filename qualifiers appearing in the program symbol 
table. This allows source files to be found (by searching the directories specified 


with - 1) even if they were moved after the executable was generated. 


The name of the program to execute. 


Arguments to be pass to the program. — 


Example xcdb -I/u/derek/myproject -e2000 -c20 -i14 -i30 stuff one two three 


invokes Xcdb and: 


« Runs the program stuff with arguments “one two three” 


# Looks for source files in either the current directory or the directory 
/u/derek/myproject 


# Displays up to 2000 elements for any array 


# Displays up to 20 functions in the Callers window pane 
# Ignores signals 14 (SIGALRM) and 30 (SIGUSRI), passing them directly to 
the program without stopping 
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To interrupt a running program and return to the debugger, point the mouse to 
the window from which the program was invoked and press Ctrl-c. 


To resume execution, left-click the Run command. 


NN ao oS a ee Le eer ae 


Xcdb exit codes 


To exit the debugger, left-click the Exit command. 


You can also terminate the debugger and executing program by pressing Ctrl-\ 
on the xterm window from which you invoked the debugger. Do this only if both 
the debugger and the program are unresponsive to keyboard input. 


Wena n eee a nen eeseneamen er ene tune neces anew esas ee ans eseneee 


The exit code Xcdb returns to the operating system is determined as follows: 
_« If the program terminated normally, Xcdb returns the value passed by the 
program to its exit() function. 
# If the program terminated due to an exception, Xcdb returns 255. 
« If Xcdb terminated abnormally, then a value of | is returned. 
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Listing Displays the source code for the function selected in the Callers or Functions 
windows, the file selected in the Files window, or a breakpoint selected in the 
Breakpoints window. The window’s title indicates the file’s name. 


Set or clear a breakpoint by clicking on the line to affect. If the source file was used 
to generate code multiple times (as for functions generated from a C++ template 
file or an out of lined inline), a menu prompts you to choose the function instance 
to breakpoint. | 


Locals Displays variables defined in the scope of the function selected in the Callers 
window. Click on a value in this window to activates a display-format menu (see 
“Format Control” on page 130). 


NonLocals Displays variables defined outside the scope of any function (this includes static 
C++ class members), grouped by translation unit. Click on a value in this window 
to activates a display-format menu (see “Format Control” on page 130). 


Callers Displays a traceback of suspended function activations (most recent at top). Click 
on a function name to display the source code for that function in the Listing 
window and to display its local variables in the Locals window. 


Functions Displays the names of the functions comprising the program. Click on a name to 
display the source code for that function in the Listing window. 


Files Displays the names of the source files comprising the program. Click on a name to 
display the source code for that function in the Listing window. 


Breakpoints Displays a list of breakpoints currently set. Click on a breakpoint to display the 
source code for that breakpoint in the Listing window. Lines with breakpoints are 
marked with stop sign icons. 


Command Displays the commands which can be used to control the debugger. Click on 
command to execute it. 


Messages This window pane displays messages from time to time. It is invisible unless there 
| is a message to see. 
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Window and mouse clicks display and control all aspects of the debugger. 


Left button The left button manipulates the contents of a window. To scroll a window, drag the 
contents; the contents scroll in a direction and amount proportional to the 
motion of the mouse. 


Title bar Brings up a menu: 
Move Changes the window's position 
Resize Changes the window’s size 
Lower Pushes the window down 
Minimize Reduces the window to an icon 
Normalize Restores the window’s original size 
Maximize Enlargse the window to fit the application window 


Horizontal $.B Togglse horizontal scrollbars on or off 

Vertical $.B. Toggles vertical scrollbars on or off 
End of a scroll bar Scrolls the contents one line or column (fast click) or one page (slow click)’. 
Middle of a scroll bar Sets the window to an absolute position on the contents (position is 


Right button The right mouse button changes the shape, position, or visibility of a window. 


Center of window To drag the window to a new position. 


Right-click without moving the mouse pushes the window 
beneath any other windows it might have been obscuring. 


Corner or edge of window To resize the window. 
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Keys Keys navigate through the window, and execute searches. 
Enter Makes a selection; same as left-click. 
Arrow Moves cursor, scrolling the window if necessary. 
Page-up Scrolls window back. 
Page-down Scrolls window forward. | 
Home Moves cursor to first column of window. : 
End . Moves cursor to last column of window. 
“ann Moves cursor to line number nnn (but not past end of file). 
/XXXX Search forward to next occurrence of the string XXXX; omit the XXXX to repeat 
search from current position. 
\XXXX Moves cursor backward to preceding occurrence of XXXX; omit the XXXX to 


repeat search from current position. 
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Issue commands by left-clicking on an item in the Commands window to bring 
up the Commands menu. 


Commands Run 
Line step 


Call step 
Return step 


Signal 


Edit 


Restart 


Exit 


Executes the program until a breakpoint is encountered or a signal is received. 


Executes the program until a breakpoint is encountered, a signal is received, or control 
passes to a new line of source code. Executes functions called by the current line without 
stopping. 


Executes the program until a breakpoint is encountered, a signal is received, control passes 
to a new line of source code, or a function call is made. 


Executes the program until a breakpoint is encountered, a signal is received, or control 
returns to the caller of the current function. 


Resumes execution at the current instruction, passing whatever signal caused the 
interruption back to the program. Any signal sent to the program interrupts execution and 
returns control to the debugger. Signals can arise from: 


A signal key (Ctri-c, for example) clicked in the controlling terminal’s window. You probably want 
the program to ignore the signal and so would resume execution with the Run command. 

A signal received in an alarm() or wait() system call. You probably want the program to process 
the signal and so would resume execution with the Signal command. 

A signal generated by a runtime exception. Execution cannot continue, but the debugger can 
still inspect the environment that caused the exception. Re-execute the program with the 
Restart command. 


Invokes an editor on the file in the Listing window. Specifies the editor withxcdb. Edit in 
your .Xdefaults. Use %s and %d symbols for filename and line number, respectively. For 
example, to invoke vi: 

xcdb.Edit: (xterm =+0-0 -n Vi -e vi t%d %s &) 
To invoke emacs: 

xcdb.Edit: (emacs '+%d' ‘"%s' &) 
To invoke v: 

xcdb.Edit: (v -1 4%4d &%s &) | 
Terminates the program, reloads it, and sets its execution point back to the beginning; all 


breakpoints and data format selections remain unchanged. If stdin is a file, it is rewound to 
start-of-file. 


lf the debugger was attached to a process using -a, then the process is allowed to resume 
execution (if you want the process to die, you must use kil] -9 from an xterm window— 
there’s no explicit command to do this from Xcdb); otherwise, the process terminates and 
the debugger returns to the operating system. 


read only). Xcdb handles this by running the program until the kernel function returns to the point of call. 
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You can reformat objects in the Locals and NonLocals windows in a variety of 
ways, depending on their type. 


Point the cursor to an object’s name or value and left-click to invoke a menu. 


Point the cursor to a menu selection and click again to reformat the object as specified. 


Click outside the menu (or on its title bar) to close the menu without making a change, 


and leave the object’s format unchanged. 


Address of 
Type of 
Size of 
save 
Recall 


Edit 


char 
int. 
unsigned, 
Float 
enum 
function 


class, struct, or 
union 


array 


pointer 


A singly quoted letter: ‘a’ 

A signed integer: -123 

An unsigned integer: 4294967173 
A floating point number: 1.23 

An enumerator name. 

A function name. 


A class name (or a member list, see “class, struct, 
and union formatting” on page 132). 


The word “array” (or an element list, see “Array 
formatting” on page 134). 


The word “ptr” (or a pointed-to object, see “Pointer 
formatting” on page 137). 


Displays the object’s memory address. 


Displays the object’s type. 
Displays the object’s size. 


Remembers the object’s display format for later reference by Recall. 


Changes the object’s display format to match that of the object most recently 


referenced by Save. 
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Integer 


Float 


Complex 


Class, Struct, or Union 


Class 


Array 


PRELIMINARY 


Tyas: specific F Rana: 
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Character 
Signed 
Unsigned 
Ocial 


decimal. 
Scientific 


Decimal 
Scientific 
Hex 


More detail 
Less detail 
Show self 


Less detail 
String 


select subrange 
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Type-specific formatting options are also available. 


Letter format: ‘a’ 
Signed integer format: -123 
Unsigned integer format: 4294967173 


Octal format: 0177 


Hex format: Ox 


“f” format 
“e” format 
Hex format: Ox7t 


Real and imaginary parts of the number i in “p" format. 
Real and imaginary parts of the number in “e” format.. 


Displays the real and Imaginary parts of the number | in nex format — : 


Reveals the members, horizontally. 

Reveals the members, vertically. 

Hides the members. 

Runs the object’s xcdb( ) member function (if any). See “Self-displaying C++ 


Reveals array elements. Oo 
Hides array elements. 
Displays an array of characters as a null terminated string: “abc”. 
Selects a subrange of the array for display. A prompt asks for the subscripts of the 


elements you: wish to see. ‘See’ “Array formatting” on page 134. 


TALIGENT INTERNAL TOOLS 


131 


132 CHAPTER Q XCDB 
FORMAT CONTROL 


Pointer Less detail Hides the pointed-to object. 
Hex The pointer in hex format. 
String A pointer to character as a null terminated string. 
Array At pointer to X as an array of X. 
Select subrange A selected subrange of the pointed-to array. A prompt asks for the elements you . ! 
wish to see. : , } 
Cast Changes (casts) the base type of the pointed-to object. A list of struct, union, and | 


typedef names prompts to select a new base type. Subsequent formatting of the 
pointed-to objects treats them as if they are of the type you select. 


Downcast Converts a C++ pointer to abstract base class into a pointer to most derived class 
by inspecting the pointed-to object’s virtual function table pointer. 


Less detail Hides the pointed-to object, for example: 


class X { ... };// base class 


class Y : public X { ... }; // derived class 
FO). ee 
X X; 


g(&); // pass a ‘pointer-to-X' 


yy; 
g(&y); // pass a 'pointer-to-Y' 
i} 


g(X *p) { // at run time 'p' could be either 
: // "pointer-to-X' 
// or "pointer-to-Y' 
// 


// click on 'p" and select "Downcast' 
// to reveal the actual type 


} 
siaeee struct, and Choosing More detail multiple times on a structure reveals increasing levels of 
union formatting detail. At the minimum level of detail, only the structure name displays. At the 


maximum level of detail, all of the member names and values display. Similarly, 
clicking Less detail successive times causes the ues s format to fold up. 
Consider the following declaration: 
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Click More detail here -—— 


ClickMore detail here 


struct node 
{ 
struct node *next; 
struct data 
{ 
int type; 
float value; 
} data; 
} Node = { 0, { 1, 123 } }; 


This sequence shows how you might inspect the object: 


Node: node 


Node: { NULL data } 


Node: next: NULL 


ClickMore detail here ——— data: data 


Node: next: NULL 


Click More detail here ———— data: {1 123.000000 } 


Click More detail here 


Node: next: NULL 
data: type: 1 
value: 123.000000 


Node: next: NULL 


data: type: 1 
value: 123.000000 


Node: next: NULL 


_ data: { 1 123.000000 } 


Node: next: NULL 


Click Less detail here ——— data: data 


Click Less detail here 


Click More detail here 
Click Type here —————--—- 


Click Hex here —---------~- 
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Node: { NULL data } 


Node: node 
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You can also examine just a particular field of interest by clicking on that field: 


Node: { NULL data } 


Node: { NULL { 1 123.000000 } } 


Node: { NULL { 1 float } } 
Serta aod 


Node: { NULL { 1 0x42f60000 } } 
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Array formatting Xcdb displays arrays similar to structures, except that the elements are identified 
by indices rather than member names. At the minimum level of detail, only the word 
“array” displays. At the maximum level, the indices and values of all the array 
elements display. : 


Statically allocated arrays © Consider the following declaration. 


Struct point 

{ 

char *name; 

int coord[3]; 

} Set[] = { 
{"one", {01 Ady, 
{"two", {2,2,2}}, 
{"three", {3,3,3}}, 
{"four", {4,4,4}}, 
{"five", {5,5,5}}, 
1° StxX" {6,6,6}}, 
ie 


This sequence shows how you might inspect the object: 


set: array 
ClickMore detail here ————! 


Set: { point point point point ... } 
ClickMore detail here ——— | 


Set: 0: point 
Click More detail here ———— 1: point 
2: point 
3: point 
Set: 0: { ptr array } 
ClickMore detail here ——----4?_4, Ptr array } 


2: { ptr array } 
3: { ptr array } 


Set: 0: { ptr array } 
1: name: ptr 

Click More detail here ————____©0Ord: array 

: 2: { ptr array } 

3: { ptr array } 


Set: 0: { ptr array } 
1: name: ptr 
coord: { 2 2 2 } 
2: { ptr array } 
3: { ptr array } 
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Dynamically allocated In the previous section, the array dimensions were defined at compile time and 

arrays known to the debugger. But for arrays with runtime defined dimensions, the 
debugger has no idea of the outer array dimension, so it assumes a value of 1 
until you tell it otherwise. Consider the following declaration: 


main() 
{ 
char **stuff = malloc(3 * sizeof(char *)); 
stuff[0] = "abc"; 
stuff{1] = "def"; 
stuff[2] = "ghi"; 
return 0; 
} 


To format stuff as an array of character pointers, step the program until the 
array has been completely initialized, and then: 


Stuff: ->->0x6l 
CCK SEP ING Nee aeons) 


Stuff: ->"abc"™ 
Click Select subrange - 
here, enter “0,2,...” 


stuff: { "abc" "def" NULL } 
Click More detail here ~~! 


stuff: 0: "abc" 
1: "def" 
2: “ghi"™ 
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Subrange selection 


Select specific subranges of array elements by clicking on the array and choosing 
Select subrange from the menu. Then, type the subscript or range of subscripts 


of the element(s) that you wish to see. Use an expression of the form: 


subrangeSpecifier 


sectionSpecifier 


subdimensionSpecifier :: 


sectionSpecifier { ',' sectionSpecifier }... 


"LE" subdimensionSpecifier { "," subdimensionSpecifier }... '"]' 

10 hi // subdim elements between lo and hi, inclusive | 
10 " '*" 7// all elements of subdimension, starting at 'lo' 

“** "hi // all elements of subdimension, ending at '‘'hi' 

ea " '*" // all elements of subdimension 

ee // all elements of subdimension 

n // n’th element of subdimension 


The count of subdimensionSpecifiers must match the count of array 
dimensions. Here are some examples: 


char arrayL4](2]; 


LOe S| 


ee re rea er ee 


// a 4 by 2 array 


// matches elements: [0,0] 


[0,1] 


// matches elements: f1,1] 


rare e 
[3,0] 
[3,1] 


If a subrange specifier would display more than 1,000 elements, then the 


remainder display as “...”. Change this limit by specifying a different value using 


-e or the xcdb.ArrayLimits item in .Xdefaults. 
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Pointer formatting At the minimum level of detail, only the word “ptr” displays for a pointer object. 
Click More detail to reveal the pointed-to object. Consider the following: 


typedef int (*FUNCP)(); /* a function pointer * / 
FUNCP Table[3] = { main, exit }; /* table of pointers */ 


The sequence below shows how you might inspect the object: 


Table: array 
ClickMore detail here ———— 


Table: { ptr ptr NULL } 
ClickMore detail here ————- 


Click More detail here ee 


CHICK TY pO POL annette 
Table: O: -> main() 
1: ptr 
2: NULL 
Click Type here 
Table: 0: -> function-returning-int 
1: ptr 
2: NULL 


Table: 0: pointer-to-function-returning-int 
Click Type here glee Sar 1: ptr 


NULL 


i) 


Table: 3-item-array-of-pointer-to-function-returning-int 
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Set or remove unconditional breakpoints by clicking on the line in the Listing 
window. Set or remove conditional breakpoints that releate to the line indicated 
by the pointing hand icon as follows: 


Run the program to the line where the breakpoint is to be set. 


® If you set a breakpoint to get there, remove it. 


 Left-click on an integer or pointer object in the Locals or NonLocals window, 
and select Breakpoint from the menu. 


Enter a breakpoint trigger value for the object, at the prompt. 


Xcdb indicates the breakpoint with a stop sign icon on the source line and with 
an asterisk-marked (*) entry in the Breakpoints window 


Xcdb stops the program whenever the specified line executes, and the object has 
the specified trigger value. 
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PREFERENCES 
Seneca 
To specify your preferences, use the Preferences option from the Commands 
menu in the Commands window. 
Preference settings Language Controls printing of variable names and interpretation of array element addresses. 


Normally, Xcdb determines the language automatically, based on the initial stopping 
point in the program. You can change this by clicking either mouse button to cycle 
through the possibilities: 


C Array element addresses are computed in row majorform. 
C++ Array element addresses are computed in row majorform; variable 
names are demangled; nested class members are labeled. 
FORTRAN Array element addresses are computed in column majorform. 
Variables Controls printing of variables in the Locals window pane. 


Lexically scoped __ Displays only the variables in the scope of the current instruction. 


Unscoped Displays all variables in the current function, even those in other 
lexical blocks. This option is a work-around for a bug in some 
compilers—see “Frequently asked questions” on page 142. 


Secret variables | Controls visibility of C++ compiler-generated variables. 


Hidden Does not display secret variables. 
Visible Displays secret variables. 
Include Files Controls interpretation of file symbols appearing in the symbol table. 
Respect The debugger makes use of #incl ude file information appearing 


in the symbol table. 


Ignore The debugger ignores #inc1ude file information appearing in the 
symbol table. This option is a work-around for bugs in cpp, cc, 
and. cfront—see “Frequently asked questions” on page 142. 


File search path Specifies the directories to search when displaying source files in the Listing window. 
Enter a list of directory names, separated by spaces. See also the description of -s. 


Upon fork follow Controls tracing of fork( ) system calls: 
Parent 7 Follows the parent process after a fork() 
Child Follows the child process after a fork() 


When stepping through a fork( ) statement, you must use Line Step and not Call 
Step; otherwise, the debugger gets stuck trying to trace the system call. 


Autoraise Controls automatic raising of interior window upon mouse entry. 


Detail per click Controls the count of levels of detail to reveal (hide) when requesting More detail (Less 
detail) on a structure, union, array, or pointer object. Right-click 0 increase the value, 
and left- “click to decrease ih 
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This is an experimental feature that allows C++ objects in a program to show 
themselves in response to a request from the debugger. When a C++ object is 
selected on the Locals or NonLocals window, and you choose Show self from the 
menu, Xcdb executes a member function named xcdb(), if found. For every class 
you wish to examine, write an xcdb() member function with these constraints: 


# no arguments 

# Of type void 

* must not be inline 

se every Class must have its own xcdb() member function (they cannot be 
inherited; they may be virtual, but must be defined for each subclass) 


When you want a class instance to run its xcdb() member function, click on the 
object (as usual), format the object as a “structure” (choose More Detail if you 
only have a pointer to the object), and choose Show self. This runs the object’s 
xcdb() member function. Control then returns to the debugger. 


An xcdb() member function can be written to do anything at all. It might say 
something interesting, display pretty pictures, and so on. Use your imagination. 


class Mumble 


{ 

private: const char *name; 

public: Mumble(const char *name) : name(name) {} 
public: const char *name() { return name; } 
public: void xcdb(); 
i; 


void Mumble::xcdb() { printf("My name is '%s'.\n", name()); } 


main() 
{ 
Mumble& mumble = *new Mumble("“mumble"); 
} 


Clicking on the variable “mumble” in the Locals pane and selecting Show self 
from the menu displays 


My name is ‘mumble’. 


in the xterm window that invoked the debugger. 


Attempting to Show self on aclass or struct for which no xcdb() member 
function is defined produces a complaint, but is otherwise harmless. 


Any breakpoint or exception inside the xcdb() member function, while running 
in the context of Show self, terminates the function (returning control to Xcdb), 
and is otherwise ignored. 
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General 


Layout 


Create layout entries from 
your working environment 
with -1; see “Running” on 
page 123 for information. 


POOLE LL LILES ETT OLEEL EOE TOL EOE REEL CETEE OE Ls 


CUSTOMIZATION 


Change. Xcdb’s window shape, position, font, colors, and window layouts with 
\$HOME/ .Xdefaults. For information about available fonts and colors see /usr/ 
Ipp/X11/defaults/Xfonts and /usr/1ib/X11/rgb.txt, respectively. 


The following tables summarize the .Xdefaults entries. Values to the right of the 
colon indicate acceptable entries, where: 


geometry is a geometry specification such as “100x300+10-5” 
font is the name of a font, such as “Rom10.500” 
color 7 is the name of a color, such as “Slate Blue” or “#7AD” 
ee ae ; ae ae a ee ene eT ee ene 
Font: font Font to use for text 
AutoRaise: on |off Behavior of window when mouse enters 
saveUnder: on |off Handling of pixels obscured by popup menus. On some X servers, 


popup menus run faster with SaveUnder set on; others run faster with 
SaveUnder set off. Try both settings and see which works best for you. 


The layout entries customize each window in the debugger. You must specify settings for all or none of 


the windows; you cannot specify some of the windows. 
SpecialLayout: yes | no Do window specifications follow? 
xxxxGeometry: geometry Size and placement for normal window 


xxxxiconGeometry: geometry Size and placement for iconized window 


xxxxiconifyOk: yes | no Permit iconization of this window? 
xxxxiconStartup: yes | no Iconize window at start-up? 
xxxxocrollbars: vertical | scrollbar style 


horizontal | both | none 


where xxxx is one of Callers, Functions, Files, Breakpoints, Commands, Listing, Locals, NonLocals, 


Formats, or Messages. 
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Color 


Xcdb ignores color entries 
on monochrome displays or 
when -bw or-wb has 
been specified. 


Other 


PRELIMINARY 


Borderldle: color 
BorderActive: color 
Foreground: color 
Background: co/or 
MouseBody: color 
MouseOutline: color 
CursorForeground: color 
CursorBackground: color 
MarkForeground: color 
MarkBackground: color 
TitleForeground: color 
TitleBackground: color 
DialogForeground: color 
DialogBackground: color 
DimForeground: color 
DimBackground: color 
scrolibuttonidle co/or 
ScrollbuttonActive color 
Editor: command 


Language: language 


RespectincludeFiles: yes | no 
ArrayLimits: NNNN 
DetailPerClick: MW 
UnsignedCharFormat: 


decimal | hex 


UnsignedShortFormat 
decimal | hex 


TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


CHAPTER 9 XCDB 
CUSTOMIZATION 


Window borders, mouse outside 
Window borders, mouse inside 
Normal text 

Normal text 

Mouse body 

Mouse outline 

Cursor 

Cursor 

Marked text 

Marked text 

Window pane titles 

Window pane titles 

Command lines 

Command lines 

Non-selectable menu items 
Non-selectable menu items 
scroll buttons, mouse outside 
scroll buttons, mouse inside 


The specified command is invoked when the Edit command is selected 
from the Commands window (see earlier). 


The debugger’s behavior is adjusted for the specified /anguage, as 
described in the Preferences menu section (see earlier). language 
must be one of: 


z C 
we C++ 
z FORTRAN 


Controls interpretation of file symbols appearing in the symbol table, 
as described in the {\it Preferences} menu section (see earlier). 


Controls data formatting, as described for the “-e” command line flag 
(see earlier). 3 


Controls data formatting, as described for the “-d” command line flag 
(see earlier). 


Selects default data formatting style for unsigned char numbers. 


Selects default data formatting style forunsigned short numbers. 
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xcdb.Font: 
xcdb.Background: 
xcdb.Edit: 


xcdb.RespectIncludeFiles: 


xcdb.ArrayLimits: 
xcdb.DetailPerClick: 
xcdb.UnsignedCharFormat: 
xcdb.FloatFormat: 
xcdb.AutoRaise: 
xcdb.SaveuUnder: 


Rom17 .500 

Slate blue 

(emacs '+%d' '%s' &) 
yes 

2000 

2 

hex 

scientific 

on 

of f 
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FREQUENTLY ASKED QUESTIONS 


Here are the answers to some frequently asked questions. 
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Q: This document makes reference to menu item XXXX, but I don’t see it on my 
menu. 

A: Your window pane is either too small or the item has scrolled out of view. Press 
Home and then use the cursor keys to scroll the window contents until you find 
the item you are looking for. 

Q: A window pane or menu appears to be empty. 

A: See the answer to the previous question. 


Q: My program runs fine when invoked from the debugger, but doesn’t run when 
invoked from the shell command line. 


A: Unlike the command shell, Xcdb loads your program without searching the 
$PATH environment variable. You’ve probably got a program by the same name 
somewhere in your $PATH. Try explicitly qualifying the program name when you 
type it on the command line. For example, type: 


./test abc #4 run program in current directory \end{verbatim} 
instead of: 


test abc # oops, this probably invokes /bin/test \end{verbatim} 
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Q: The debugger stops with a Signal 0 when it encounters the system() function 
in my program. 

A: This is normal. Just click the Signal item on the command pane to continue, 
or reinvoke Xcdb with “—i 0.” 


Q: I can’t set a breakpoint on some lines of my C++ program (compiled with 
cfront). 


A: There are bugs in /1ib/cpp, the preprocessor used by cfront to perform 
macro expansion. Try another macro preprocessor—some people have had luck 
with /usr/1pp/X11/Xamples/util/cpp/cpp. Point to it with the CC’s “cppC” 
environment variable, and then recompile. 


There are also bugs in cfront related to generation of #1 ine directives for 
templates and include files. Try setting Include files: /gnore in the Preferences 
menu and see if this helps. 
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Q: Xcdb displays the wrong source file and/or line number in my C++ program 
(compiled with cfront). 


A: Try setting Include files: Jgnore in the Preferences menu and see if this helps. 
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Q: Xcdb displays the wrong source file and/or line number in my C++ program 
(compiled with xIC). 


A: Make sure you have set Include files: Respect in the Preferences menu. Another 
possibility is that the source file contains more than 65,534 lines. Due to an AIX 
symbol table design feature, line information for such files is stored incorrectly. 
The only workaround is to split the source file into smaller pieces. 
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Q: I can’t see one of my local variables, but I know it’s there. 


A: This is due to a compiler bug. Try the Variables: Unscoped option on the 
Preferences menu. | 
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Q: My program seems to be running correctly, but the variables displayed by 
Xcdb look wrong. 


A: You probably compiled your program with both -g and -0. The resulting 
compiler optimizations confuse the debugger. Recompile your program with 
either -g or -0, but not both. 
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Q: I can’t see code generated from #inc1ude files. . | 


A: You need a newer version of x1C (such as version 01.02.0000.0000, or later). | tC 
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A: You probably tried to set a breakpoint on an instruction that was one of several 
“instantiations” generated from the same #include file. | 


If you are debugging template code generated by the x1C compiler, make sure 
you ve set the Language: C++ option on the Preferences menu. 


Otherwise, if you are debugging non-template code, or code generated by 
compilers other than x1C, there is no mechanism by which Xcdb can infer the 
instruction instantiation to which you refer, so it is not possible to seta 
breakpoint on the specified line. Sorry. 
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Q: I can’t see a traceback in the Callers window pane when I set a breakpoint in a 
signal handler. 


A: This is a deficiency in Xcdb that is being addressed. 
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Q: I get an error when attempting to attach the debugger to a process using -a. 


A: This seems to have something to do with shared libraries. If you can reproduce 
this problem with a small program, please send a bug report to the Taligent Tools 
Team. | 
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Q: Xcdb is sluggish when stepping. How can I make it faster? 


A: Display update performance during stepping operations can be improved by 
icontfying the NonLocals window pane if it is not needed. The debugger is then 
saved the expense of reading and formatting (potentially large) amounts of 
global data from the program’s execution image. Also, choosing the -n 
command line option will help here, by reducing the number of symbols that 
Xcdb must search. Reducing the size of the main window or using a larger font 
will also help, because it reduces the amount of window drawing that takes place. 
Also, enabling xcdb.SaveUnder in your .Xdefaults file may improve performance 
of pop-up menus (see “Customization” on page 140). 
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Q: How can I format a number of variables, all in the same style, without 
tediously clicking more detail on each one? 


A: Try using the Save and Recall selections on the Formats menu to propagate 
the formatting information from one object to all the others. 


Q: How can I change the display format of all the elements of an array at once, 
without tediously clicking on each one? 


A: Try this: 
Format the first item in the array 


Use Select subrange to (re)select the elements you wish to see 


The format of the first element propagates through to all the other elements 


Q: How can I invoke Xcdb from inside my program? 


A: Try something like this: 


main() 
{ 
foo(); 
} 


foo() 
{ 
bar(); 
} 


bar() 
{ 
trouble(); 
} 


-trouble() 


{ 

extern char **p_xargv; /* undocumented variable */ 
char cmd[100]; 

sprintf(cmd, "xcdb -a %4d 4S", getpid(), p_xargv[0]); 


if (fork() — 0) 


system(cmd); 7* runs Xcdb */ 
else | 
pause(); /* waits until Xcdb issues "Run", "Line Step", etc. */ 


} 
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Q: When I Select a subrange, | only see the first 1,000 elements of my selection. 
Where are the rest? 


A: As a safety feature, Xcdb displays at most 1,000 elements per array. Use -e or 
xcdb.ArrayLimits in your .Xdefaults file to change this limit. 


PAPAL MAPO LID L EEL P LIL MPP LOLOL PIL ELL OOD LOPLI DDO PLOL LLP IL LOL MPL IL ILL EL LLLP ELE P LPL IPL PL IL ILL DOLE LILL OPEL POEL LEE LOE LEPC ILL L LILLE ILL OODLE SIL OLE L LLLP LLP PIL ELL IPL LILLIPL ELLE EP EP LP LLP ELLE LIL IOI LIE L ODPL ILE DLL ELL EIL EE OEP LLP PIPPI LEIP OS EL EL LADS I DLL EL OLLIE LDL LLL LLLP PIL IL IDL EPL LOOP LER OLLEPLIPPEL LEQ PL IP IPE LEPL IES LLLP IEIL IPL IPIL ELE IIE OL LPL LPL ILIL LLL IL ILE PL OP OPS De 


Q: How can I display a region of memory as an unstructured hex dump 
A: Try this (ok, it’s a bit of a kludge, but it works): 


Determine the address of the region you wish to inspect (using Format...as 
address, for example) 


Take any convenient char pointer in your program and set its value to the 
address you wish to inspect (using Edit) 


Select the number of elements to be displayed (using Select subrange) 
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A: Type xcdb (no arguments) to find out. 
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Q: Where can I get the latest version of Xcdb? 
A: Obtain XCDB6000 PACKAGE from your nearest AIXTOOLS service machine. 
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Q: What’s new in the latest version of Xcdb? 


A: Please read the XCDB6000 NEWS file that is shipped with each XCDB6000 
PACKAGE. 
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Q: I have a question that isn’t answered here. 


A: Please report any problems you discover (or wish list items) to the Taligent 
Tools ‘Team. 
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If you encounter a problem with Xcdb, file a Taligent bug report. 
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CHAPTER 10 


GDB 


To debug the Taligent Operating System, use the GNU Debugger (6 DB). This 
chapter help you use the GDB debugger quickly. For more detailed: information, | 
refer to the GDB Reference Manual. For information about debugging Taligent 

Application Environment, see Chapter 9, “Xcdb.” 
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diet eieiatdd GCDB 
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Internal Note The installation procedures have not been finalized at this time. 
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To debug MyProgram (a runpink executable): 
Place MyProgram. Herbie in the source-code directory, if you want symbols. 
You can also specify the symbol-table file with the -se command-line option. 


| At the UNIX shell prompt, run gdb and specify the name of the program to 
debug: 


% gdb MyProgram 
GDB Taligent Version 4.11.D7 (rs6000-ibm-aix3.2), 
Copyright 1993 Free Software Foundation, Inc. 

The GDB command prompt —--———— (gdb) 


GDB is now ready to start debugging. 


NOTE For information about rp executables, see “Debugging shared 
libraries and rp-executables” on page 154. 
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Source-level _ By default, GDB looks for source-level debugging source-code in the current 


debugging directory. To specify another directory, use directory or the -cd command-line 
| option: 


(gdb) directory /home/Work/Ta1igent/Development/Portable/Albert/Source 


To search multiple directories, use dir, or the -d command-line option, to adda 
directory to the search path: 


(gdb) dir /home/Work/Taligent/Development/Portable/Albert/Test 


To report which directories are in the search path, use show dir: 


(gdb) show dir 
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RUNNING GDB 


To start you program, use run. If the program needs command-line arguments, 
include them on the run command line: 


(gdb) run argl arg2 


You can also use set args to set command-line arguments, and info args to find 
out what they are. 
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To get online help, use help. For help on a specific topic, specify the topic. 


(gdb) help breakpoints 
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To quit GDB, use quit. If you need to quit while a program is running (and you 
can’t get to the GDB prompt), use Ctrl-C. 
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Resuming execution 


To set a breakpoint, use breakpoint (which you can abbreviate to b). To break 
when entering a function, specify the function name: 


(gdb) b myfunc 

To break at a particular line number in a specific file: 
(gdb) b mysourcefile.C:228 

To break at a specific address: 


(gdb) b *0xdef00000 


C++ mangles the names of member functions. To choose the member function 
from a list, specify the class and function name, followed by a tab character: 


(gdb) b ‘fooclass::foofunc<TAB> 
{¢NOTE Breakpoints can have a pass count or a condition, and you can 


execute commands after a breakpoint occurs. Type help break for more 
information. 


To resume program execution, use continue. To step command-by-command, or 


until a specific event, follow the instructions in the next section. 
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To step between function calls or machine instructions, use these commands: 


step Steps one source code line. 

next Steps over a function call. 

stepi Steps one machine instruction. 

nexti Steps one machine instruction, stepping over function calls. 


All of the variants of step and next accept a pass count, for example to step 
twenty lines at once: 


(gdb) step 20 


For more specialized control: 


finish Finishes a function. 


until Tinenumber Runs until linenumber. Be careful, if your program doesn’t 
reach this line number, your program can hang. 


return value Forces a return with the optional given value. 
goto /abel Forces a goto in the program you are debugging. 
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GDB has several commands for examining data. 
print expression Prints, in a formatted manner, the value of an expression. 
x address Examines (or dumps) a memory address. 


memberfunc Toggles printing of member functions. 
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TRACING INSTRUCTIONS 


Taligent’s version of GDB has an instruction-trace facility. To use it, set up GDB in 
the usual way, and run to the breakpoint where you wish to start tracing. Then, 
put your trace into a file with outfile and begin the trace: | 


(gdb) outfile MyTracefile 


You can trace to an end of function, a discrete number of instructions, or a 
particular address: | 


(gdb) trace 
(gdb) trace 500 
(gdb) trace 0xd1c40000 


When you are finished, close the output file by calling out file with no 
arguments: 


(gdb) outfile 
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DEBUGGING SHARED LIBRARIES AND RP-EXECUTABLES 


To debug shared libraries and rp-style executables: 
Make sure you have these files: 
# The rp program and one extra terminal session. 


# The shared library version of LLSystemLib (the nonshared library version 
is LLSystem.1ib). 


# LLSystemLib.Herbie and your target program’s .Herbie file in the same 
directory where you run LLSystemLib. 


Start the library server in the extra terminal session, this becomes the libserver 
session: | 


rp _libserver 


Run GDB and LLSystemLib in your original session, this is the gdb session: 


gdb LLSystemLib 


Once the (gdb) prompt appears, LLSystemLib is in memory, _StaticDataInit 
has been called, and you can set breakpoints in LLSystemLib. 
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CHAPTER 10 GDB 
DEBUGGING SHARED LIBRARIES AND RP-EXECUTABLES 


EX Use run to execute the program: 


run MyProgram argl arg2 


Before running your program, LLSystemLib calls GDB’s 
LibraryLoadedCallBack function, which causes GDB to load 
MyProgram.Herbie to retrieve the symbolic information. 


NOTE As it is currently enabled, GDB’s LibraryLoadedCallBack function 
causes a break into the debugger so that you can set breakpoints in your program 
before it runs. (Eventually there will be a mechanism similar to the 68K ci’s 

run -d option.) When this break occurs, GDB prompts something like this: 


Reading symbols: your_program.Herbie 
Symbol base at 0x20400108 
LibraryLoadedCalIlBack: Doing breakpoint 
Gdb selected thread NN 


Program received signal SIGTRAP (5), Trace/BPT trap 
Oxab8c4 in ?? () 


LibraryLoadedCallBack is defined not to have symbolic information display for 
itself, hence the hex address. Use where to see the LLSystemLib stack trace. 


To list all shared library symbol tables loaded, use info shared: 


(gdb) info shared 
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CHAPTER 10 GDB 
PROBLEMS AND OTHER USEFUL INFORMATION 
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If you encounter a bug in GDB, file a Proteam bug report—GDB should soon be 


a component on the bug tracking system. meanwhile, here are some known 
problems and remedies: 


# Your copies of gdb and gdbnub must be checked with the blessit script. As 
the root user, run blessit on both files. Once these files have been checked, 
1s -1 shows the following permissions and ownership: 


-rwSPrwxr-X 1 root system 


Ss 


« Your machine should be running snames and machid. Run ps -A | grep 
snames to see if it has been set up to do so. 


# Variable and type information is not currently supported. Use the x to 
examine memory. | 


# When you are using LLSystemLib, attaching to a program that is blocked ina 


system call works as far as getting the current user state, but the program — 
aborts if you step, continue, or detach. 


Bay 


Internal Note Got any clues as to why? 


« If you don’t get a complete stack crawl when running LLSystemLib or 

multiple threads, run t1, and try it again. It usually works the second time. 

« Don’t restart a program in the same GDB session once the program 
terminates or is already running. Instead, quit and restart GDB and your 
program. , 

# Sometimes when continuing from a breakpoint, the program seems to hang. 


If you Ctrl-C to interrupt it, GDB shows that it didn’t continue from the 
breakpoint. 
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« The Debugger call currently isn’t provided in LLSystemLib. For your program 
to give control to the debugger, execute an int 3 breakpoint instruction. 
One way to do this is to link an assembly module, Debugger.s, to your 


program: 

Debugger function extern 
char Oxcc 
ret 
end 


Assemble it as follows: 
Assembler.x86 Debugger.s 


« The current version has some thread support. The thread commands for 
Mach conflicted with the standard GDB thread commands, so Taligent 
changed them by modifying the command prefixes to mthread and mtask 
(help mthread and help mtask reveal which commands are available). Where 
a thread argument use the MID, not the slot number. | 


The following aliases are defined: 


mth mthread The prefix 
t] mthread Jist Display thread list 
ts mthread select Select a thread 


GDB has the concept of a current thread that determines which registers and 
stack is displayed. The current thread is initially the thread where the 
breakpoint is hit. ts and mthread select specify a different thread to be the 
current thread. t] and mthread 1ist report the known threads. Use the MID 
number to specify threads in all the commands. In the thread list, the 
current thread is marked with an “*” following the MID. 


« Ifyou step inside a function with no source map information GDB might give 
you a message like “Cannot access memory at address 0,” or some message | 


about not knowing the size of the function. Some of this will eventually be 
fixed. For now, use one of the following: 


# Si (perhaps with display) to assembly step 
« finish to go to the end of call 


frame to change to a frame with source and then set a breakpoint 
following the call you are in 
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APPENDIX A 


TIps & TECHNIQUES 


Everybody has their own work style, but there are some simple tricks you can do 
to make yourself more productive. Here are some useful pointers. | 


This chapter assumes you have the standard AIX environment. Make sure you set 
up your account to the specifications defined in Chapter 2, “Working in the AIX ee 
environment.” a a ee ae Baie, 


CDPATH 


The cdpath shell variable contains a list of directories that shell searches when 
you use cd. For example, if you are in your $HOME directory, you can type: 


cd Envious 


and the shell will take you right there. The shell looks in the current directory 
first, and if it does not find Envious there, it searches the directories in cdpath, 
which is what happens in the previous example. 


This little trick saves a massive amount of typing when you are navigating around 
the Taligent source tree. Here is an example of settings to add to your .cshrc file: 


set cdpath=( ~ \ 

${HOME} \ 

${HOME}/Taligent \ 

${HOME}/tools \ 

${HOME}/Taligent/Toolbox \ 
${HOME}/Taligent/Toolbox/InternationalUtilities \ 
${HOME}/Taligent/Toolbox/Document2 \ 
${HOME}/Taligent/Toolbox/Runtime \ 
${HOME}/Taligent/Albert/Main \ 
${HOME}/Taligent/Instrumentation/TestSystem\ 
${HOME}/Taligent/Time \ 

/home/local \ 
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Taligent uses xcdb (an internal IBM project) as its Taligent Application 
Environment debugger. Be sure to read Chapter 9, “Xcdb,” before using this 
debugger. However, there are two things that can make your work with xcdb 
easier: 


# Use SCMFetch to checkout sources from the SCM source data base (for more 
information, see“SCMFetch” on page 34). 


« Use the suggested .Xdefaults file for standard behavior. 


Instead of calling xcdb directly, use the xdb script which install SCMFetch and turns 
off some interrupts that you probably do not need. 
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Within the Taligent Application Environment, OpusBug() is a function that calls a 
UNIX program script which runs a debugger to attach to your running process. 
OpusBug( ) emulates the functionality of the DebugStr() call found in many 68K 
development environments. While fairly limited because the UNIX environment 


is very different than other development environments, OpusBug() provides the 


rudiments of printing a message and starting a debugger. 


Within the Taligent Operating System, OpusBug() prints a debugging string, and 
then calls the debugger. 


sree 


€ NOTE The origin of the name OpusBugis lost in obscurity. 
When you call OpusBug() within the Taligent Operating System it prints a 
message, and drops directly into the debugger. 


When you call OpusBug() within the Taligent Application Environment, it 
prints a message. 
# uses system() to call pink_debugger: the program script. pink_debugger must 
be in your $PATH. 
# then puts your process to sleep for five seconds. This is generally enough 
time for a debugger to get started and attach to the process to be debugged. 
The debugger comes up with sleep() on the top of the stack; below sleep() 


should be OpusBug() and then the routine that called OpusBug(). You should 
be able to debug from there. 
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Because OpusBug() invokes pink_debugger via a system() call, it carries a few 
restrictions: 


« The pink_debugger script must terminate with an exit status of zero. 


« The pink_debugger script must not be blocking. This means that anything 
that requires interaction, like a debugger, must be run in the background. 


Here is the prototype for OpusBug(): 
void OpusBug(char *message); // Print the message, and call pink_debugger 


OpusBug() passes two arguments, the process ID and the calling program name, 
to provide enough information for a debugger to attach to a running process. 


Here is a sample pink_debugger. 


#! /bin/sh 
i 
4 This program starts an xdb session in the background. 
i 
Arguments from —----—-—-_ PROCESS_ID=$1 
echo 
echo 
echo "*** Entering pink_debugger ***" 
echo "*** PROCESS ID == $PROCESS ID ***" 
echo "*** PROGRAM NAME == $PROGRAM NAME ***" 
Calll the debugger —--------. taldb -a $PROCESS_ ID $PROGRAM_NAME & 
echo "*** Exiting pink_debugger ***" 
Must return 0 —-_------ exit 0 


To print the message, but not start a debugger, pink_debugger should be nothing 
more than exit with a zero return status. 


d## Do not start the debugger 
exit 0 


To neither print a message nor start a debugger ( do nothing), set the 
PINK_DONT_USE_OPUSBUG environment variable. 


setenv PINK_DONT_USE_OPUSBUG 
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EMACS 


Emacs shell 


Create a new shell 


Create multiple shells 
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Fi—Build 


Many engineers use the Emacs editor on AIX. This section details certain major 
aspects of Emacs that you might find useful if you use the editor. 


AIX has built-in terminals (A/XTerms) that most users do not need or like. As 
such, users tend to prefer using Emacs in shell mode, which is similar to an MPW 


Worksheet because you can scroll back, edit, and re-execute commands (unlike 
in AlXTerm). 


To create an emacs shell session: 
Press ESC-x 


Type shell. 


To have multiple shells sessions open, first rename your open shell buffer: 
Press ESC-x 


Type rename-buffer 


Then create another new shell. 
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This section provides detail about each function key including, how and when 
you can use them. Each table includes the key, the command that Emacs 


- executes, and a brief description of the action. 


On page 168, you will find a function key quick reference to post next to your 
workstation. 


Use F1 to build your subsystems. Emacs calls Makeit to execute a build (see 
page 66 for Makeit specific information). You can type these commands in the 
shell buffer, but it is better to use Fl because Emacs redirects the output of the 
build is *compilation* buffer, which is used by the error finding key, F2. 


selmi 0 gee a a Mee ea 
By default, Fi builds Includes, Objects, Exports, and Binaries for the current project and 


all its subprojects. You can change the default target by typing new target. 
Ctrl-F1 Makeit Clean Complete 


Executes a clean build on the current project and all its subprojects. If you change these 


targets, they will not be remembered next time you use C-F1. 
S-F1 Makeit -c [target] 


Builds the specified target in the current project only. Emacs remembers target after you 
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Meta-F1 Makeit Binaries 


Builds the binaries target for the current and all it’s subprojects. This is useful for 
rebuilding shared Libraries. If you change these targets, Emacs does not remember 
them the next time you use Meta-F1. 


Meta-Sh-F1 Makeit -c Binaries 


Builds the binaries target for the current project. This is useful if you have already built a 
single subproject, and you want to rebuild a shared library that is built in the parent 
directory. 


Ctrl-Sh-F1 Makeit -c Clean Complete 


Executes a clean build on the current project only. If you change these targets, Emacs 
does not remember them the next time you use Ctrl- FI. 


F2—Locate compiler Locates errors or warnings generated during a compile, and which are in the 
messages *compilation* buffer. To get the compiler messages in this buffer, use F1. 
F2 Locate Next Message 


Opens the file to the location that the compiler message refers to. This key finds 
(W)arnings, (E)rrors that the compiler fixed, and (S)erious errors that break the build. 
Note: you can use F2 to locate the result of a search, see below. 


Sh-F2 Locate Next Serious Error (Not implemented yet) 
Finds the next (S)erious compiler error, and skip the(E)rror and (W)arning messages. 


Meta-F2 Locate Next Error Message (Not implemented yet) 
Finds the next (S)erious or (E)rror compiler message, and skip the (W)arning messages. 


Internal Note Are the keys implemented yet? 


SE a 


‘-@ NOTE Theses keys might not work with the Comptech compiler. 


F3—Search Searches (grep) for patterns in specific locations, and redirects the result to a 
special buffer that F2 can use locate the match. 


F3 Searches Taligentincludes 
Prompts you for a pattern and then searches for that pattern in$TaligentIncludes, 
$TaligentPrivatelncludes, and then your local project, in that order. 

Sh-F3 Searches Current project (Wot implemented yet 
Prompts you for a pattern and then searches for the pattern in your local project. 


Meta-F3 General purpose search 


Prompts you with a grep (search) command for general purpose searches. Unlike a 
terminal, the result goes toa special buffer so you can view the matches with F2. 
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F4 —Taligent AIX layer Starts and stops the Taligent AIX reference layer, and a Taligent application 
within that layer. 


Eexecutes StartPink to start the AIX reference layer. 
Sh-F4 Stops the AIX Layer 


Executes StopPink to stop the AIX reference layer. Does not kill applications that are 
running; you must close those application first. 


Ctri-F4 Starts a Taligent application 


Launches the specified application. Emacs remembers the application name after the 
first time you type it in. 


Meta-Sh-F4 Starts a Taligent application with xcdb 


Launches the specified application using the xcdb debugger. Emacs remembers the 
_ application name after the first time you type it in. 


F5—Goto Goes to and reports your location in the buffer. 


F5 | GoTo line 
| Prompts you for a line number, and then takes you to that line in the current buffer. 
Ctrl-F5 What line? | 
Prints the cursor’s line number to the status line. 
Sh-F5 GoTo Help | 
Brings up a buffer with a quick reference to all the function keys. 


F6 and F7/—Change Switches your current buffer. There are many other ways to change your current 
buffers buffer, but this makes it easy. 


= eet 75771550 Sa ga cea 
Brings the last buffer you visited (before current one) to the current buffer. 
Sh-F6 Burry buffer 


Puts the current buffer last in the list of buffers and brings the front most buffer in the 
list to the front. Think of this as a buffer que. 


F/ Next buffer 
Bring. 

Sh-F7 Unburry buffer 
Bring. 
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F8—Open Opens the current selection, or open the .PinkMake for the current project. 


Open a file by the name of the current selection. Searches $TaligentIncludes, 
$TaligentPrivatelIncludes, and the current directory. Useful in opening header 
files by select the filename on the #incl ude line. 


Sh-F8 Opens Current PinkMake 
Opens the .PinkMake file for the current project. 
Ctrl-F8 Comments-out current selection 
Put C++ style comments at the beginning of each line in the current selection. 


F9, F10, and F11— Defines and runs keyboard macros. Macros are useful when you have to perform 
Keyboard macros repetitious editing tasks. If you find yourself running a sequence of commands 
over and over again, it might be efficient to define a macro for the commands. 


F9 start keyboard marco 
Begins recording commands and key strokes. 


F10 End keyboard macro 
Stop recording. 


F11 Call last keyboard macro 
Execute the last keyboard macro recorded. 


To name the last macro to save it for later use (and not record over it): 


Press ESC-x 


Type name-last-kbd-macro and press Return. 


Emacs then prompts you for the name. 


F12—Find and replace Searches and replaces strings. 


Emacs prompts you for the search string, then prompts you for the replacement string. 
Emacs then moves your insertion point to the first occurrence of the string and prompts 
you about replacing the string. It then goes to the next occurrence. 


Sh-F12 Replace string 


Does a global search and replace; Emacs prompts you for the search string, and then 
prompts you for the replacement string. 
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EMAGS . 


F13 (Print Screen) — 
Checkout 


F14 (Scroll Lock)— 
Checkin key 


Navigation keys 


AoC IS SAKA LILLE MM SLID CLEA ALN ARS ALLA SAE PEL, 


Checks out the current buffer for modification. A second buffer shows the 
Checkout information. 


Checks in the current buffer to its RCS project A second buffer shows the 
Checkin information. 


Here is a quick reference of navigation keys: 


ao ace 
End Move cursor to end of line 
Ctrl-Home Move cursor to beginning of buffer 
Ctri-End Move cursor to end of buffer 
Strl-Home | Move cursor to beginning of window 
sh-End Move cursor to last line of window 
PageUp : Scroll down | 
PageDown Scroll up 
Ctrl-PageUp Scroll other window down 
Ctrl-PageDown Scroll other window up 


Tags are helpful in finding class definitions and member functions. Taligent AIX 
layer system builds have a TAGS file for the Taligent include files. The standard 
Emacs configuration file (current cpg.e1) automatically loads the TAGS file. 


To use tags, place the cursor over the class or member function to look up, and 
press Esc-. (Esc-period). Emacs opens the file where that class or member 
function is defined. Esc-, (Esc-comma) finds the next occurrence of the tag. 


Stn et 


Fics 


“2NOTE The Taligent Operating System environment does not build these tag 
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Emerge is a set of Emacs macros that merge two diff files (the result of 
comparing three source files). 
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Commands 


Binding 


In edit mode, you must use C-c or C-c to begin commands; you can use 
commands in fast mode without the prefix. 


Binding 


—_ Oo 


XC 
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emerge-abort 
emerge-find-difference 
emerge-scroll-left 
emerge-scroll-down 
emerge-select-B 

Prefix command 
emerge-fast-mode 
emerge-jump-to-difference 
emerge-mark-difference 
emerge-previous-difference 
Prefix command 


Prefix command 
emerge-copy-as-kill-B 


emerge-default-B 

emerge-insert-B 

emerge-skip-prefers 
emerge-set-combine-versions-template 
emerge-split-difference 


emerge-line-numbers 


emerge-file-names 


emerge-combine-versions 


Xt 
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negative argument 
digit argument 
emerge-scroll-right 
emerge-select-A 

Prefix Command 
emerge-edit-mode 
Prefix Command 
emerge-recenter 
emerge-next-difference 
emerge-quit 


emerge-scroll-up 


emerge-scroll-reset 


emerge-copy-as-Kill-B 
emerge-default-A 
emerge-insert-A 
emerge-auto-advance 
emerge-split-difference 


emerge-set-merge- 
mode 


emerge-join-differences 


emerge-combine- 
versions-register 


emerge-one-line- 


window 
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EMERGE 
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Emacs function keys 


ETL 


Emerge has several modes of operation. 
Fundamental mode is used for comparison with the other modes. 


Emerge mode minor mode (indicator is emerge) is used by Emerge when merging files, 
and can be entered through one of the functions: : 


emerge-files 
emerge-files-with-ancestor 
emerge-buffers 
emerge-buffers-with-ancestor 
emerge-files-command 
emerge-files-with-ancestor-command 
emerge-files-remote 
emerge-files-with-ancestor-remote 


Emerge fast mode minor mode (indicator is /—fast mode) disables ordinary Emacs 
commands, and Emerge commands do not need a C-c or c-c prefix. 
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Key Function Description 
as, = ae : saul Fete deren ihe Sten eed + en eee 
Ctrl-F1 makeit-clean-complete Makeit clean complete 
Sh-F1 makeit-c Makeit -c_ 
Meta-F1 makeit-binaries Makeit binaries 
Meta-Sh-F1 makeit-c-binaries Makeit -c binaries 
Ctrl-Sh-F1 makeit-c-clean-complete Makeit -c clean complete 
1a. ie Cer ost cae : Grane al eee ee 
and search =p search-in-pinkincludes Search for pattern in include directories 
| Ctrl-F3 grep Search for pattern 
Tra ae = eee accan ee ee Senin eee ee et ee eee ee 
layer Meta-Sh-F4 start-pink-xdb-app Start a Pink application under xdb control 
Sh-F4 stop-pink Stop Pink! 
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Function 
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Description 


Got and 
change 
buffer 


goto-line 
what-line 
open-heipfile 
previous-buffer 
next-buffer 
bury-buffer 
unbury-buffer 


Go to specified line number 

Display current line numbers 

Display this help file 

Go to previous buffer in buffer list 

Go to next buffer in buffer list 

Push this buffer to the end of the buffer list 
Oops--bring it back to the front 


Open files 


open-selection 
cplus-comment-region 


open-pink-makefile 


Open current selection as a file 


Make lines in current selection into C++ comments 
(insert //) 


Open the standard Pink makefile in . (current 
directory) 


Keyboard 
macros 
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Fi2 
Ctrl-F12 
PrintScreen 
ScrollLock 
Pause 


Sh- Pause © 


Home 

End 

Ctrl-Home 
Ctrl-End 
sh-Home 
sh-End 
PageUp 
PageDown 
Ctrl-PageUp 
Cirl- -PageDown 
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start-kbd-macro 
end-kbd-macro 
call-last-kbd-macro 
query-replace 
replace-string 
check-out-buffer 
check-in-buffer 
cpg-emerge 


cpg- Special- merge | 
beginning- -of-line 


end-of-line 
beginning-of-buffer 
end-of-buffer 
beginning-of-window 
end-of-window 
scroll-down 

scroll-up 


scroll-other-window-down 


scroll- other-window- up 


Start recording keyboard macro 

Stop recording keyboard macro 
Execute last recorded keyboard macro 
Query replace! 

Replace string! 

Check out current file from SCCS 
Check in current file to SCCS 
Three-way merge of file revisions - 
Three- “way merge of specific builds © 
Move c cursor to beginning offline = | 
Move cursor to end of line 

Move cursor to beginning of buffer 
Move cursor to end of buffer 

Move cursor to beginning of window 
Move cursor to end of window 

scroll down! 

Scroll up! 

Scroll other window down 

scroll other window up 
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TLTALIGENT SOURCE CODE 
MAINTENANCE 


Taligent source code is stored in a hierarchy of directories maintained by our 
SCM tools. To check source code in and out of SCM, you must first create a 
directory hierarchy in your workspace that mirrors the SCM hierarchy. 


To set up your working environment to work with the Taligent source code eas 
maintenance system (SCM), follow the steps in Chapter 2, “Working in the AIX 0 
environment.” . 


Taligent uses the following terms and definitions when discussing source code 
management: 


«« Project —a directory that contains source code, other projects (subprojects), 
or both. 
# Project hterarchy—a tree of projects of arbitrary depth. 


# Workspace—your own directory hierarchy that mirrors the source code 
project hierarchy. You check out files to your workspace. 


« TaligentRoot—the root of your workspace hierarchy. The path to TaligentRoot 
is contained in the $TaligentRoot shell variable. 


# TahgentSCMRoot—the root of the source-code server hierarchy. The path to 
TaligentSCMRoot is contained in the $TaligentSCMRoot shell variable. 


$TaligentSCMRoot is a link to the SCM repository. Use this logical directory to 
access the repository because the physical directory can move. 
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PROJECT HIERARCHY 


NOTE This diagram is a snapshot of the hierarchy—the hierarchy can and 


will change until code freeze. 


Platform: specific. 42x ce eee eee “ raligen | ponennrenneee, Glue code for AIX 
code 4 


CONTAINS COE nnrnnnccnnncesceeeeeeeetttttene 
common to all 
platforms 


AES OWNS ore Vi 
this code 


AES/OS code based 
on OS interfaces 


nee Native platforms 
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PROJECT HIERARCHY 


As an Taligent engineer, you have a mirror of the SCM hierarchy on your local 
file system. The mirrored directory structure is your workspace or working directory. 
When you retrieve or check out a file from the SCM hierarchy, Checkout places 
the file in your corresponding working directory. For example, if your home 


directory is /home/arn, then your working directory hierarchy is probably 
underneath /home/arn/Work. 
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& (background command), 12 
~ (home directory), 4 


A 


AIX, 1 
logging out, XII, 4 
AIX reference layer 
See layer 
analysis tools, 99 
applications 
background execution, 12. 
building, 43, 68 


running, 12,51 


background execution, 12 
Basic Acceptance Tests 
See BATS, XIx 
BATs, XIx 
binaries, 41 
build 
clean, 52 
definition, 41 
Emacs, using, 162 
environment variables, 46 
examples, 48 
generating, 66 
global targets and rules, 45 
installing Layer, 5 
installing Native, 7 
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log listing, 50 
mistake, one target, 44 
phases of, 42 
process, 42 
system build, 57 
terminology, 41 
build tools, 59-75 
building projects, 41-57 


C 


cd, shortcuts, 159 
cdpath (environment variable), 159 
changing directories, shortcuts, 159 
Checkin, 19 
checking in 
files, 9,19 
files with Emacs, 166 
new files, 9 
checking in and out, 8-11 
checking out 
files with Emacs, 166 
latest version, 38 
latest versions, 39 
Checkout, 22 
class 
description files, storage location, 11 
opening editor to definition, 166 
client files, 41 
CompareVersions, 24 
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comparing files, 24 E 
between workspace and RCS, 33 
checking out latest, 38 

compiler 
error, goto with Emacs, 163 
options, 48 | 
warning, goto with Emacs, 163 

copying files, 74 

cp 
See SmartCopy 


ic 
See export file 
Emacs, 162—166 
buffer switching, 164 
building subsystems, 162 
checking in files, 166 
checking out files, 166 
class definition, opening to, 166 


cpg.el, 166 *compilation* buffer, 162 
CreateMake compiler error in file, goto, 163 
definition, 60 | Emerge macros, 167 
syntax, 77-97 function key summary, 168 


goto line, 164 

layer, starting and stopping, 164 

line number, report current, 164 
macro recording, 165 

member function definition, opening to, 166 
D | navigation keys, 166 . 
open selected file, 165 

opening .PinkMake files, 165 

replace, 165 

search, 165 

search for patterns, 163 


.cshre | 
directory shortcuts, 159 
.cshrc (startup script), 3 


.d files, storage location, 11 
debugger 
See xcdb 
debugging, getting matching source file, 34 
diff, called by SCMDiff, 33 


difference between files, 24 aa po 
ree . environment variables 
~ (home directory), 4 a aer 
changing to, shortcuts, 159 ie » 4 se od 
creating to match project, 32_ ae NB a 
$home, 4 . r 
home, 4 Undefined symbol”, 62 


error message 
“Environment variable must be set!”, 5 
error message, “names file could not be checked out”, 18 
executables 
building, 68 
definition, 41 
executing applications, 51 
export file 
definition, 41 
generating, 65 


name, normalized, 37 
source tree, making your copy, 5 
working, creating, 4 
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file 
attributes, setting and getting, 31 
checking in, 19 
checking out latest version, 38 
comparing against another file, 24 
comparing against project, 24 
comparing against RCS, 33 
copying, 74 
filename, normalized, 37 
locks, breaking, 31 
modifiable, reporting, 26 
opening with Emacs, 165 
revision history, 36 
TAGS, 166 
unlocking, 23 
version, latest trunk in workspace, 26 
version, listing, 26 
filenames, normalized, 37 
FindSymbols, 61 


G 


generating 
builds, 66 
executables, 68 
export files, 65 
libraries, 69 


-h 

See header file 
$Header:$, 9 
header file, 41 
heap corruption, 104 
heap tools, 99 
hierarchy, workspace, 173 
history, revision, 36 


$home, 4 
home directory 
ie 4 
$home, 4 
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include-file tags (Emacs), 166 
InstallDefaults, 3 
installing builds, 5, 7 
InterimInstall, 64 
IPCPurge, 65 

See also mop 


kill, 14 


Latest, 26 

latest files, checking out, 39 

layer, 12 
cleaning up after, 12 
Emacs, starting and stopping with, 164 
restarting, 12 


starting, 12 
stopping, 12 
libraries 


building from smaller libraries, 44 
generating, 69 
linking to export files, 65 
links, symbolic, 4 
ListVersions, 26 
lock 
breaking, 31 
unlocking, 23, 31 
logging out of AIX, xII, 4 
.login (startup script), 3 
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macro recording with Emacs, 165 
make 
receiving options from Makeit, 45 
See also Makeit, 44 
.Make, missing builds new makefile, 45 
MakeC++SharedLib, 69 
MakeExportList, 65 
makefile, 43-44 
description 
check in to RCS, 43 
naming convention, 43 
standard makefile, translating to, 43 
syntax, 43 
target types, 43 
standard makefile, creating, 43 
syntax, 43 
targets, 43 
when to build, 45 
Makeit, 44-45 
definition, 66 
log listing, 50 
makefiles, when to build, 45 
passing options to make, 45 
MakeSharedApp, 68 
MakeShredLib, 69 
MakeSOL, 69 
member function 
description files, storage location, 11 
opening editor to definition, 166 
MHeapDiscipliner, 110 
mop, 70 
mro, 23 
-Mwmnrec (startup script), 3 
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name, assigning symbolic, 28 i 
names (symbolic names file), 18 | \. 
NameVersions 
definition, 28 
modes of operation, 29 
native | 
program stopping, 14 | 
programs, running, 13 
Nativelnit, 6 
NativeInstall, 70 
NativeRoot, 31 
new files, 9 
NewRootCommand, 48 


0 


options 
compiler, 48 
overridding with variables, 47 


P 


pathname 
file in working directory, 37 
normalized form, 37 
_ working directory, returning, 37 
PBI, 32 
.PinkMake 
newer than *.Make, 45 
opening with Emacs, 165 
.profile (startup script), 3 
programs 
background execution, 12 
building, 68 
running, 12 
project 
building, 44 
building subprojects, 44. 
creating new, 21 
definition, 171 
project hierarchy, 171 
See also project 
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R 
reference layer 

See layer 
replace with Emacs, 165 
resources, purging, 65 
$Revision:$, 9, 36 

from SCMInsertHeader, 36 
revision history, 36 
rlog 

See SCMLog 
rm, called by SyncSources, 38 
rp, 71 
RunDocument, 72 
running applications, 51 
runpink, 14, 73 


S 


SCCS tag lines, removing, 36 
SCM 

definition, 171 

terms and definitions, 171 

tools, 17-39 
SCMAdmin, 31 
SCMCreateDirectories, 32 
SCMDIff, 33 
SCMFetch, 34 
SCMInsertHeader, 36 
SCMLog, 36 
SCMNormalize, 37 
SCMProjectFile, 37 
ScreamPlus, 70 
scripts, 3 

InstallDefaults, 3 

Nativelnit, 6 

startups, downloading, 3, 6 
search with Emacs, 165 
SsetRoot 

definition, 38 

script location, 48 


PRELIMINARY TALIGENT CONFIDENTIAL: REGISTERED INFORMATION 


INDEX 


shared libraries 
building, 43 
definition, 41 
generating, 69 
linking to export files, 65 
SharedLibCache, 73 
Slcache 
See SharedLibCache 
Slibclean, 74 
SmartCopy, 74 
source code 
location, 171 
tree, making your copy, 5 
source code maintenance 
See SCM 
SSTs, xXIx 
StartPink, 75 
startup scripts, 3, 6 
StopPink, 75 
subproject, building, 44 
Subsytem Tests 
See SSTs, xX1x 
symbolic links, 4 
symbolic names 
assigning, 28 
description of, 18 
SyncSources, 38 
system build, 57 
system tests 
tests, system, XIX 
System Tests Applications, xIx 
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T 


TAbstractHeapBlock, 110 
TAddressPeeker, 108 
tags (Emacs), 166 
$TaligentRoot 
normalized pathname requirement, 37 
setting, 5 
TaligentRoot, 171 
.-TaligentSCM (subdirectory), 18 
$TaligentSCMRoot, 171 
TaligentSCMRoot, 171 
TBlockEvent, 107 
TBlockEventHandler, 108 
TCallChain, 113 
terminology, SCM terms and definitions, 171 
THeapAnomaly, 112 
THeapBlock, 109 
THeapMirror, 110 
THeapMirrorException, 112 
tips and techniques, 159 
TLocalHeapAnalyzer, 102, 107 
TLocalHeapMonitor, 101, 106 


U 


Universal .Make, 45 
Universal .Make.Intel, 45 
unlock, 23 


V 


- version 
file, latest trunk in workspace, 26 
listing a file’s, 26 
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working directory, creating, 4 
workspace 

definition, 171 

hierarchy, 173 


X 


xcdb (debugger), 160 

xdb, 160 

.Xdefaults. (startup script), 3 
.xinitrc (startup script), 3 
xLC, wrapper for, 68 
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